Index: trunk/psModules/src/camera/pmFPAMaskWeight.h
===================================================================
--- trunk/psModules/src/camera/pmFPAMaskWeight.h	(revision 7715)
+++ trunk/psModules/src/camera/pmFPAMaskWeight.h	(revision 9594)
@@ -1,12 +1,22 @@
-#ifndef PM_READOUT_MASK_WEIGHT_H
-#define PM_READOUT_MASK_WEIGHT_H
+/// @file pmFPAHeader.h
+///
+/// @brief Functions read FITS headers for FPA components
+///
+/// @ingroup Camera
+///
+/// @author Paul Price, IfA
+/// @author Eugene Magnier, IfA
+///
+/// @version $Revision: 1.5 $ $Name: not supported by cvs2svn $
+/// @date $Date: 2006-10-17 02:21:03 $
+///
+/// Copyright 2005-2006 Institute for Astronomy, University of Hawaii
+///
+#ifndef PM_FPA_MASK_WEIGHT_H
+#define PM_FPA_MASK_WEIGHT_H
 
 #include "pmFPA.h"
 
-// these defines are necessary to yield 8-bit results (use instead of ~)
-#define NOT_U8(A)(UCHAR_MAX-(A))
-#define NOT_U16(A)(USHORT_MAX-(A))
-
-/** Mask values */
+/// Pixel mask values
 typedef enum {
     PM_MASK_CLEAR   = 0x00,   ///< The pixel is not masked
@@ -21,23 +31,50 @@
 } pmMaskValue;
 
-// These functions set an extant mask/weight (or create a throwaway one).
-// The throwaway case is intended for when the user is iterating using pmReadoutReadNext, in which case
-// the HDU can't be generated
-bool pmReadoutSetMask(pmReadout *readout // Readout for which to set mask
+
+/// Set a temporary readout mask using CELL.SATURATION and CELL.BAD
+///
+/// Identifies pixels that are saturated (>= CELL.SATURATION) or bad (<= CELL.BAD).  The mask that is produced
+/// within the readout is temporary --- it is not added to the HDU.  This is intended for when the user is
+/// iterating using pmReadoutReadNext, in which case the HDU can't be generated.
+bool pmReadoutSetMask(pmReadout *readout ///< Readout for which to set mask
                      );
-bool pmReadoutSetWeight(pmReadout *readout // Readout for which to set weight
+
+
+/// Set a temporary readout weight map using CELL.GAIN and CELL.READNOISE
+///
+/// Calculates weights (actually variances) for each pixel using photon statistics and the cell gain
+/// (CELL.GAIN) and read noise (CELL.READNOISE).  The weight map that is produced within the readout is
+/// temporary --- it is not added to the HDU.  This is intended for when the user is iterating using
+/// pmReadoutReadNext, in which case the HDU can't be generated.
+bool pmReadoutSetWeight(pmReadout *readout ///< Readout for which to set weight
                        );
 
-// These functions generate a mask/weight suitable for output (complete with HDU entry) and then set them.
-bool pmReadoutGenerateMask(pmReadout *readout // Readout for which to generate mask
+/// Generate a readout mask (suitable for output) using CELL.SATURATION and CELL.BAD
+///
+/// Identifies pixels that are saturated (>= CELL.SATURATION) or bad (<= CELL.BAD).  The mask that is produced
+/// is suitable for output (complete with HDU entry).  This is intended for most operations.
+bool pmReadoutGenerateMask(pmReadout *readout ///< Readout for which to generate mask
                           );
-bool pmReadoutGenerateWeight(pmReadout *readout // Readout for which to generate weight
+
+/// Generate a weight map (suitable for output) using CELL.GAIN and CELL.READNOISE
+///
+/// Calculates weights (actually variances) for each pixel using photon statistics and the cell gain
+/// (CELL.GAIN) and read noise (CELL.READNOISE).  The weight map that is produced within the readout is
+/// suitable for output (complete with HDU entry).  This is intended for most operations.
+bool pmReadoutGenerateWeight(pmReadout *readout ///< Readout for which to generate weight
                             );
 
-// These functions are conveniences for pmReadoutGenerateMask and pmReadoutGenerateWeight.
-bool pmCellGenerateMaskWeight(pmCell *cell // Cell for which to generate mask and weights
+/// Generate mask and weight map for a readout
+///
+/// Calls pmReadoutGenerateMask and pmReadoutGenerateWeight for the readout
+bool pmReadoutGenerateMaskWeight(pmReadout *readout ///< Readout for which to generate mask and weights
+                                );
+
+/// Generate mask and weight maps for all readouts within a cell
+///
+/// Calls pmReadoutGenerateMaskWeight for each readout within the cell.
+bool pmCellGenerateMaskWeight(pmCell *cell ///< Cell for which to generate mask and weights
                              );
-bool pmReadoutGenerateMaskWeight(pmReadout *readout // Readout for which to generate mask and weights
-                                );
+