Index: /trunk/psModules/src/detrend/pmFlatNormalize.c
===================================================================
--- /trunk/psModules/src/detrend/pmFlatNormalize.c	(revision 9613)
+++ /trunk/psModules/src/detrend/pmFlatNormalize.c	(revision 9614)
@@ -13,12 +13,9 @@
 // few with absolutely no trouble (it *is* over-constrained).  For this reason, I'm putting the maximum number
 // of iterations and tolerance as preset values.
-#define MAXITER 10
-#define TOLERANCE 1e-3
+#define MAXITER 10                      // Maximum number of iterations
+#define TOLERANCE 1e-3                  // Minimum tolerance for convergance
 
-// Estimate the flat-field normalisation; return the source flux in each integration
-bool pmFlatNormalize(psVector **expFluxesPtr, // Flux in each exposure; modified for return
-                     psVector **chipGainsPtr, // Initial guess of the chip gains; modified for return
-                     const psImage *bgMatrix
-                    )
+
+bool pmFlatNormalize(psVector **expFluxesPtr, psVector **chipGainsPtr, const psImage *bgMatrix)
 {
     PS_ASSERT_PTR_NON_NULL(bgMatrix, false);
Index: /trunk/psModules/src/detrend/pmFlatNormalize.h
===================================================================
--- /trunk/psModules/src/detrend/pmFlatNormalize.h	(revision 9613)
+++ /trunk/psModules/src/detrend/pmFlatNormalize.h	(revision 9614)
@@ -1,12 +1,32 @@
+/// @file pmFlatNormalize.h
+///
+/// @brief Normalize flat-field measurements
+///
+/// @ingroup Detrend
+///
+/// @author Paul Price, IfA
+///
+/// @version $Revision: 1.5 $ $Name: not supported by cvs2svn $
+/// @date $Date: 2006-10-17 20:49:10 $
+///
+/// Copyright 2004-2006 Institute for Astronomy, University of Hawaii
+///
+
 #ifndef PM_FLAT_NORMALIZE_H
 #define PM_FLAT_NORMALIZE_H
 
-#include "pslib.h"
+#include <pslib.h>
 
-// Normalise the flat-field measurements (f_ij = g_i s_j where f_ij is the flux recorded for chip i and
-// integration j, g_i is the gain for the i-th chip, s_j is the flux of the source in the j-th integration).
-bool pmFlatNormalize(psVector **expFluxesPtr, // Flux in each exposure; modified for return
-                     psVector **chipGainsPtr, // Initial guess of the chip gains; modified for return
-                     const psImage *bgMatrix
+/// Normalise flat-field measurements
+///
+/// We have f_ij = g_i s_j where f_ij is the flux recorded for chip i and integration j, g_i is the gain for
+/// the i-th chip, s_j is the flux of the source in the j-th integration.  An initial guess for the chip gains
+/// might be helpful, but is not necessary.  The matrix of background measurements contains the background for
+/// the flat fields used in the combination, as a function of exposure (rows) and chip (columns).  The
+/// exposure fluxes and chip gains are modified upon return with the solved values.  Returns true if the
+/// solution converged.
+bool pmFlatNormalize(psVector **expFluxesPtr, ///< Flux in each exposure, or NULL; modified
+                     psVector **chipGainsPtr, ///< Initial guess of the chip gains or NULL; modified
+                     const psImage *bgMatrix ///< Background measurements: rows are exposures, cols are chips
                     );