Changeset 9572 for trunk/psModules/src/concepts/pmConcepts.h

Timestamp:

Oct 13, 2006, 4:35:39 PM (20 years ago)

Author:

Paul Price

Message:

Adding const where appropriate. Adding doxygen documentation to header files. Removing comments on functions defined in the header file, so that there's only a single source.

File:

• trunk/psModules/src/concepts/pmConcepts.h (modified) (1 diff)

trunk/psModules/src/concepts/pmConcepts.h

@@ -2 +2 @@
 #define PM_CONCEPTS_H
 
-#include "pslib.h"
+#include <pslib.h>
 #include "pmFPA.h"
 
-// Function to call to parse a concept once it has been read
-typedef psMetadataItem* (*pmConceptParseFunc)(const psMetadataItem *concept, const psMetadataItem *pattern, const psMetadata *cameraFormat, const pmFPA *fpa, const pmChip *chip, const pmCell *cell);
-// Function to call to format a concept for writing
-typedef psMetadataItem* (*pmConceptFormatFunc)(const psMetadataItem *concept, const psMetadata *cameraFormat, const pmFPA *fpa, const pmChip *chip, const pmCell *cell);
+/// Function to call to parse a concept once it has been read
+typedef psMetadataItem* (*pmConceptParseFunc)(const psMetadataItem *concept, ///< Concept to parse
+        const psMetadataItem *pattern, ///< Pattern for parsing
+        const psMetadata *cameraFormat, ///< Camera format definition
+        const pmFPA *fpa, ///< FPA for concept, or NULL
+        const pmChip *chip, ///< Chip for concept, or NULL
+        const pmCell *cell ///< Cell for concept, or NULL
+                                             );
 
-// A "concept" specification
+/// Function to call to format a concept for writing
+typedef psMetadataItem* (*pmConceptFormatFunc)(const psMetadataItem *concept, ///< Concept to format
+        const psMetadata *cameraFormat, ///< Camera format definition
+        const pmFPA *fpa, ///< FPA for concept, or NULL
+        const pmChip *chip, ///< Chip for concept, or NULL
+        const pmCell *cell ///< Cell for concept, or NULL
+                                              );
+
+
+/// A "concept" specification
+///
+/// Defines the name, default comment, blank value, and functions to parse (after reading) and format (before
+/// writing) the concept.
 typedef struct
 {
-    psMetadataItem *blank;              // Blank value of concept; also contains the name
-    pmConceptParseFunc parse;           // Function to call to read the concept
-    pmConceptFormatFunc format;         // Function to call to write the concept
+    psMetadataItem *blank;              ///< Blank value of concept; also contains the name and comment
+    pmConceptParseFunc parse;           ///< Function to call to read the concept
+    pmConceptFormatFunc format;         ///< Function to call to write the concept
 }
 pmConceptSpec;
 
-// Allocator
-pmConceptSpec *pmConceptSpecAlloc(psMetadataItem *blank, // Blank value; contains the name
-                                  pmConceptParseFunc parse, // Function to call to parse the concept
-                                  pmConceptFormatFunc format // Function to call to format the concept
+/// Allocator for pmConceptSpec
+pmConceptSpec *pmConceptSpecAlloc(psMetadataItem *blank, ///< Blank value; contains the name
+                                  pmConceptParseFunc parse, ///< Function to call to parse the concept
+                                  pmConceptFormatFunc format ///< Function to call to format the concept
                                  );
 
-// Register a new concept
-bool pmConceptRegister(psMetadataItem *blank, // Blank value; contains the name
-                       pmConceptParseFunc parse, // Function to call to parse the concept
-                       pmConceptFormatFunc format, // Function to call to format the concept
-                       pmFPALevel level // Level at which to store concept in the FPA hierarchy
+/// Register a new concept for parsing and formatting
+///
+/// Defines a new concept, based on the blank value (with name and default comment), and functions to parse
+/// and format the concept.  The new concept is registered at the specified level (FPA, chip or cell).
+bool pmConceptRegister(psMetadataItem *blank, ///< Blank value; contains the name and default comment
+                       pmConceptParseFunc parse, ///< Function to call to parse the concept
+                       pmConceptFormatFunc format, ///< Function to call to format the concept
+                       pmFPALevel level ///< Level at which to store concept in the FPA hierarchy
                       );
 
-// Some specificity to reading and writing concepts
+/// Source for concepts when reading and writing.
+///
+/// Since some sources become available at different times from others, we need to provide some specificity to
+/// reading and writing concepts (or we're forced to wait until everything's available, which we don't want to
+/// do).  Concepts may be read from or written to multiple sources at once by OR-ing them.
 typedef enum {
-    PM_CONCEPT_SOURCE_NONE     = 0x00,  // No concepts
-    PM_CONCEPT_SOURCE_CELLS    = 0x01,  // Concept comes from the camera information
-    PM_CONCEPT_SOURCE_DEFAULTS = 0x02,  // Concept comes from defaults
-    PM_CONCEPT_SOURCE_PHU      = 0x04,  // Concept comes from PHU
-    PM_CONCEPT_SOURCE_HEADER   = 0x08,  // Concept comes from FITS header
-    PM_CONCEPT_SOURCE_DATABASE = 0x10,  // Concept comes from database
-    PM_CONCEPT_SOURCE_ALL      = 0xff   // All concepts
+    PM_CONCEPT_SOURCE_NONE     = 0x00,  ///< No concepts
+    PM_CONCEPT_SOURCE_CELLS    = 0x01,  ///< Concept comes from the camera information
+    PM_CONCEPT_SOURCE_DEFAULTS = 0x02,  ///< Concept comes from defaults
+    PM_CONCEPT_SOURCE_PHU      = 0x04,  ///< Concept comes from PHU
+    PM_CONCEPT_SOURCE_HEADER   = 0x08,  ///< Concept comes from FITS header
+    PM_CONCEPT_SOURCE_DATABASE = 0x10,  ///< Concept comes from database
+    PM_CONCEPT_SOURCE_ALL      = 0xff   ///< All concepts
 } pmConceptSource;
 
-// Read the concepts for the given set of fpa, chip, cell
-bool pmConceptsRead(pmFPA *fpa,         // FPA for which to read concepts
-                    pmChip *chip,       // Chip for which to read concepts, or NULL
-                    pmCell *cell,       // Cell for which to read concepts, or NULL
-                    pmConceptSource source, // The source of the concepts to read
-                    psDB *db            // Database handle
+/// Read the concepts for the given set of fpa, chip, cell
+///
+/// Attempts to read as many concepts as possible from the specified source for the specified FPA, chip and
+/// cell.  That is, it will read chip- and cell-level concepts in addition to fpa-level concepts, if the chip
+/// and cell are provided.
+bool pmConceptsRead(pmFPA *fpa,         ///< FPA for which to read concepts
+                    pmChip *chip,       ///< Chip for which to read concepts, or NULL
+                    pmCell *cell,       ///< Cell for which to read concepts, or NULL
+                    pmConceptSource source, ///< The source of the concepts to read
+                    psDB *db            ///< Database handle
                    );
 
-// Set blanks, read or write concepts at the appropriate level
-bool pmConceptsBlankFPA(pmFPA *fpa      // FPA for which to set blank concepts
+/// Set the concepts within the FPA to the blank value
+bool pmConceptsBlankFPA(pmFPA *fpa      ///< FPA for which to set blank concepts
                        );
-bool pmConceptsReadFPA(pmFPA *fpa,      // FPA for which to read concepts
-                       pmConceptSource source, // Source for concepts
-                       bool propagateDown, // Propagate to lower levels?
-                       psDB *db         // Database handle
+
+/// Read concepts for an FPA; optionally, read concepts at all lower levels.
+///
+/// Once concepts should be available for reading at the FPA-level, this function attempts to read the
+/// concepts from the specified source.  It also allows concepts to be read at lower levels by iterating over
+/// the components.
+bool pmConceptsReadFPA(pmFPA *fpa,      ///< FPA for which to read concepts
+                       pmConceptSource source, ///< Source for concepts
+                       bool propagateDown, ///< Propagate to lower levels?
+                       psDB *db         ///< Database handle
                       );
-bool pmConceptsWriteFPA(pmFPA *fpa,     // FPA for which to write concepts
-                        pmConceptSource source, // Source for concepts
-                        bool propagateDown, // Propagate to lower levels?
-                        psDB *db        // Database handle
+
+/// Write concepts for an FPA; optionally, write concepts at all lower levels.
+///
+/// This function writes all concepts for the FPA to the specified "source".  It also allows concepts to be
+/// written for all lower levels by iterating over the components.
+bool pmConceptsWriteFPA(const pmFPA *fpa,     ///< FPA for which to write concepts
+                        pmConceptSource source, ///< Source for concepts
+                        bool propagateDown, ///< Propagate to lower levels?
+                        psDB *db        ///< Database handle
                        );
-bool pmConceptsBlankChip(pmChip *chip   // FPA for which to set blank concepts
-                        );
-bool pmConceptsReadChip(pmChip *chip,   // Chip for which to read concepts
-                        pmConceptSource source, // Source for concepts
-                        bool propagateUp, // Propagate to higher levels?
-                        bool propagateDown, // Propagate to lower levels?
-                        psDB *db        // Database handle
-                       );
-bool pmConceptsWriteChip(pmChip *chip,  // Chip for which to write concepts
-                         pmConceptSource source, // Source for concepts
-                         bool propagateUp,// Propagate to higher levels?
-                         bool propagateDown, // Propagate to lower levels?
-                         psDB *db       // Database handle
-                        );
-bool pmConceptsBlankCell(pmCell *cell   // Cell for which to set blank concepts
-                        );
-bool pmConceptsReadCell(pmCell *cell,   // Cell for which to read concepts
-                        pmConceptSource source, // Source for concepts
-                        bool propagateUp, // Propagate to higher levels?
-                        psDB *db        // Database handle
-                       );
-bool pmConceptsWriteCell(pmCell *cell,  // FPA for which to write concepts
-                         pmConceptSource source, // Source for concepts
-                         bool propagateUp, // Propagate to higher levels?
-                         psDB *db       // Database handle
+
+/// Set the concepts within the chip to the blank value
+bool pmConceptsBlankChip(pmChip *chip   ///< FPA for which to set blank concepts
                         );
 
-// Set up the blank concepts
+/// Read concepts for a chip; optionally, read concepts at the FPA and cell levels.
+///
+/// Once concepts should be available for reading at the FPA-level, this function attempts to read the
+/// concepts from the specified source.  It also allows concepts to be read at the fpa level (through the
+/// parent), and the cell level by iterating over the components.
+bool pmConceptsReadChip(pmChip *chip,   ///< Chip for which to read concepts
+                        pmConceptSource source, ///< Source for concepts
+                        bool propagateUp, ///< Propagate to higher levels?
+                        bool propagateDown, ///< Propagate to lower levels?
+                        psDB *db        ///< Database handle
+                       );
+
+/// Write concepts for a chip; optionally, write concepts at the FPA and cell levels.
+///
+/// This function writes all concepts for the chip to the specified "source".  It also allows concepts to be
+/// written for the FPA, and the cell level by iterating over the components.
+bool pmConceptsWriteChip(const pmChip *chip,  ///< Chip for which to write concepts
+                         pmConceptSource source, ///< Source for concepts
+                         bool propagateUp,///< Propagate to higher levels?
+                         bool propagateDown, ///< Propagate to lower levels?
+                         psDB *db       ///< Database handle
+                        );
+
+/// Set the concepts within the cell to the blank value
+bool pmConceptsBlankCell(pmCell *cell   ///< Cell for which to set blank concepts
+                        );
+
+/// Read concepts for a cell; optionally, read concepts for the parents.
+///
+/// Once concepts should be available for reading at the FPA-level, this function attempts to read the
+/// concepts from the specified source.  It also allows concepts to be read at upper levels through the
+/// parents (note, it would not read concepts for all chips, but only the parent of this cell).
+bool pmConceptsReadCell(pmCell *cell,   ///< Cell for which to read concepts
+                        pmConceptSource source, ///< Source for concepts
+                        bool propagateUp, ///< Propagate to higher levels?
+                        psDB *db        ///< Database handle
+                       );
+
+/// Write concepts for a cell; optionally, write concepts for the parents.
+///
+/// This function writes all concepts for the chip to the specified "source".  It also allows concepts to be
+/// written for the upper levels through the parents (note, it would not write concepts for all chips, but
+/// only the parent of this cell).
+bool pmConceptsWriteCell(const pmCell *cell,  ///< FPA for which to write concepts
+                         pmConceptSource source, ///< Source for concepts
+                         bool propagateUp, ///< Propagate to higher levels?
+                         psDB *db       ///< Database handle
+                        );
+
+/// Initialise the concepts system.
+///
+/// Register the standard concepts, so that concepts may be read and written.  This function is called
+/// automatically the first time the concepts functions are used.
 bool pmConceptsInit(void);
-// Free the concept specs so there's no memory leak
+
+/// Signifies that the user is done with the concepts system.
+///
+/// Frees the registered concepts so there is no memory leak when the user checks "persistent" memory.
 void pmConceptsDone(void);
 
-// Copy all the concepts within an FPA to another FPA
-bool pmFPACopyConcepts(pmFPA *target,   // The target FPA
-                       pmFPA *source    // The target FPA
+/// Copy all the concepts within an FPA to another FPA
+///
+/// Iterates over all components of the FPA, and copies the concepts metadata from the source to the target.
+bool pmFPACopyConcepts(pmFPA *target,   ///< The target FPA
+                       const pmFPA *source    ///< The source FPA
                       );