Changeset 9588

Timestamp:

Oct 16, 2006, 2:55:01 PM (20 years ago)

Author:

Paul Price

Message:

Documenting pmFPAConstruct.[ch]. Added const to pmFPAPrint().

Location:

trunk/psModules/src/camera

Files:

• pmFPAConstruct.c (modified) (9 diffs)
• pmFPAConstruct.h (modified) (1 diff)

trunk/psModules/src/camera/pmFPAConstruct.c

@@ -250 +250 @@
     }
 
-    // MORE SUBSTITUTION OPTIONS HERE!
+    // XXX: MORE SUBSTITUTION OPTIONS HERE!
 
     psTrace("psModules.camera", 5, "Looking up %s in the CONTENTS.\n", contentKey);
@@ -385 +385 @@
 }
 
+// Return the level at which EXTENSIONS go, from the FILE metadata within the camera format
 static pmFPALevel hduLevel(const psMetadata *format // The camera format configuration
                           )
@@ -420 +421 @@
 //////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
-// Construct an FPA instance on the basis of a camera configuration
-pmFPA *pmFPAConstruct(const psMetadata *camera // The camera configuration
-                     )
+pmFPA *pmFPAConstruct(const psMetadata *camera)
 {
     PS_ASSERT_PTR_NON_NULL(camera, NULL);
@@ -464 +463 @@
 
 
-// This is the engine for the pmFPAAddSourceFrom{Header,View} functions
+// This is the engine for the pmFPAAddSourceFrom{Header,View} functions.
+// It uses the camera format configuration information to determine where HDUs go in the FPA.
 // It returns a view corresponding to the PHU
 static pmFPAview *addSource(pmFPA *fpa,       // The FPA
@@ -555 +555 @@
     // In cases 2 and 3, the CONTENTS is of type METADATA, and is either a menu (if EXTENSIONS=NONE), or a
     // list of extensions otherwise.
-    psMetadata *contents = psMetadataLookupMetadata(&mdok, format, "CONTENTS"); // The contents of the FITS file
+    psMetadata *contents = psMetadataLookupMetadata(&mdok, format, "CONTENTS"); // The contents of the file
     if (!mdok || !contents) {
         if (mdok && !contents) {
@@ -751 +751 @@
 
 
-bool pmFPAAddSourceFromView(pmFPA *fpa,   // The FPA
-                            const pmFPAview *phuView, // The view, corresponding to the PHU
-                            const psMetadata *format // Format of file
-                           )
+bool pmFPAAddSourceFromView(pmFPA *fpa, const pmFPAview *phuView, const psMetadata *format)
 {
     PS_ASSERT_PTR_NON_NULL(fpa, false);
@@ -762 +759 @@
     pmFPAview *view = addSource(fpa, phuView, NULL, format);
     bool status = (view == NULL);
-    psFree (view);
+    psFree(view);
     return status;
 }
 
-// Add an input file to the FPA
-pmFPAview *pmFPAAddSourceFromHeader(pmFPA *fpa, // The FPA
-                                    psMetadata *phu, // Primary header of file
-                                    const psMetadata *format // Format of file
-                                   )
+pmFPAview *pmFPAAddSourceFromHeader(pmFPA *fpa, psMetadata *phu, const psMetadata *format)
 {
     PS_ASSERT_PTR_NON_NULL(fpa, NULL);
@@ -790 +783 @@
     }
 
-    // is FPAname already defined, new name must match it; otherwise, warn the user that something potentially
+    // If FPAname already defined, new name must match it; otherwise, warn the user that something potentially
     // bad is happening.
     const char *currentFPAname = psMetadataLookupStr(&mdok, fpa->concepts, "FPA.NAME"); // Current name
@@ -804 +797 @@
 
 
-// Print out the focal plane structure
-void pmFPAPrint(FILE *fd,               // File descriptor to which to print
-                pmFPA *fpa,             // FPA to print
-                bool header,            // Print headers?
-                bool concepts           // Print concepts?
-               )
+void pmFPAPrint(FILE *fd, const pmFPA *fpa, bool header, bool concepts)
 {
     PS_ASSERT_PTR_NON_NULL(fpa,);

trunk/psModules/src/camera/pmFPAConstruct.h

@@ +1 @@
+/// @file pmFPAConstruct.h
+///
+/// @brief Functions to create an FPA, and add data sources to it.
+///
+/// @ingroup Camera
+///
+/// @author Paul Price, IfA
+///
+/// @version $Revision: 1.4 $ $Name: not supported by cvs2svn $
+/// @date $Date: 2006-10-17 00:55:01 $
+///
+/// Copyright 2005-2006 Institute for Astronomy, University of Hawaii
+///
+
 #ifndef PM_FPA_CONSTRUCT_H
 #define PM_FPA_CONSTRUCT_H
 
-#include "pslib.h"
+#include <pslib.h>
 #include "pmFPA.h"
 #include "pmFPAview.h"
 
-// Construct an FPA instance on the basis of a camera configuration
-pmFPA *pmFPAConstruct(const psMetadata *camera // The camera configuration
+/// Construct an FPA instance on the basis of a camera configuration
+///
+/// This is the function that creates the FPA hierarchy on the basis of the camera configuration.  The "FPA"
+/// entry in the camera configuration specifies the chips (each of type STR) with their component cells listed
+/// as the corresponding values (whitespace separated).  The FPA hierarchy is created devoid of any
+/// input/output sources (i.e., HDUs).
+pmFPA *pmFPAConstruct(const psMetadata *camera ///< The camera configuration
                      );
 
-bool pmFPAAddSourceFromView(pmFPA *fpa,   // The FPA
-                            const pmFPAview *phuView, // The view, corresponding to the PHU
-                            const psMetadata *format // Format of file
+/// Add an (input or output) source to the focal plane hierarchy, specified by a view
+///
+/// Given an FPA, add an HDU by specifying where it goes (i.e., by an FPAview).  The camera format
+/// configuration is required in order to describe how the FPA is laid out in terms of disk files.
+bool pmFPAAddSourceFromView(pmFPA *fpa,   ///< The FPA
+                            const pmFPAview *phuView, ///< The view, corresponding to the PHU
+                            const psMetadata *format ///< Format of file
                            );
 
-pmFPAview *pmFPAAddSourceFromHeader(pmFPA *fpa, // The FPA
-                                    psMetadata *phu, // Primary header of file
-                                    const psMetadata *format // Format of file
+/// Add an (input or output) source to the focal plane hierarchy, specified by a (primary) header
+///
+/// Given an FPA, add an HDU by specifying a primary header, which is used to determine the FITS file
+/// contents, and therefore the proper location for the HDU.  The camera format configuration is required in
+/// order to describe how the FPA is laid out in terms of disk files.
+pmFPAview *pmFPAAddSourceFromHeader(pmFPA *fpa, ///< The FPA
+                                    psMetadata *phu, ///< Primary header of file
+                                    const psMetadata *format ///< Format of file
                                    );
 
-// Print out the FPA
-void pmFPAPrint(FILE *fd,               // File descriptor to which to print
-                pmFPA *fpa,             // FPA to print
-                bool header,            // Print headers?
-                bool concepts           // Print concepts?
+/// Print a representation of the FPA, including its headers and concepts.
+///
+/// This function is intended for testing and development purposes.
+void pmFPAPrint(FILE *fd,               ///< File descriptor to which to print
+                const pmFPA *fpa,       ///< FPA to print
+                bool header,            ///< Print headers?
+                bool concepts           ///< Print concepts?
                );