Index: trunk/psLib/src/math/psEllipse.h
===================================================================
--- trunk/psLib/src/math/psEllipse.h	(revision 13425)
+++ trunk/psLib/src/math/psEllipse.h	(revision 15794)
@@ -2,6 +2,6 @@
  * @brief functions to manipulate sparse matrices equations
  *
- * $Revision: 1.5 $ $Name: not supported by cvs2svn $
- * $Date: 2007-05-18 14:06:09 $
+ * $Revision: 1.6 $ $Name: not supported by cvs2svn $
+ * $Date: 2007-12-12 21:01:32 $
  * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
  */
@@ -15,47 +15,69 @@
 /// @{
 
-// strucures to define elliptical shape parameters
-typedef struct
-{
-    double major;                       // Major axis
-    double minor;                       // Minor axis
-    double theta;                       // Position angle
-}
-psEllipseAxes;
+// Different representations of an ellipse
 
-// strucures to define elliptical shape parameters
-typedef struct
-{
-    double e0;				// Scale (Mxx + Myy)
-    double e1;				// Polarization 1 (Mxx - Myy)
-    double e2;				// Polarization 1 (2Mxy)
-}
-psEllipsePol;
+/// Ellipse defined in terms of axes
+typedef struct {
+    double major;                       ///< Major axis
+    double minor;                       ///< Minor axis
+    double theta;                       ///< Position angle
+} psEllipseAxes;
 
-typedef struct
-{
-    double x2;                          // Moment of xx
-    double y2;                          // Moment of yy
-    double xy;                          // Moment of xy
-}
-psEllipseMoments;
+/// Ellipse defined in terms of moments
+typedef struct {
+    double x2;                          ///< Moment of xx (Mxx)
+    double y2;                          ///< Moment of yy (Myy)
+    double xy;                          ///< Moment of xy (Mxy)
+} psEllipseMoments;
 
-typedef struct
-{
-    double sx;                          // Shape parameter in x
-    double sy;                          // Shape parameter in y
-    double sxy;                         // Shape parameter in xy
-}
-psEllipseShape;
+/// Ellipse defined in terms of Gaussian shape parameters
+typedef struct {
+    double sx;                          ///< Shape parameter in x
+    double sy;                          ///< Shape parameter in y
+    double sxy;                         ///< Shape parameter in xy
+} psEllipseShape;
 
-// conversions between elliptical shape representations
-psEllipseMoments psEllipseAxesToMoments(psEllipseAxes axes);
-psEllipseAxes psEllipseMomentsToAxes(psEllipseMoments moments, double maxAR);
-psEllipseShape psEllipseAxesToShape(psEllipseAxes axes);
-psEllipseAxes psEllipseShapeToAxes(psEllipseShape shape, double maxAR);
+/// Ellipse defined in terms of polarisations
+typedef struct {
+    double e0;                          ///< Scale (Mxx + Myy)
+    double e1;                          ///< Polarization 1 (Mxx - Myy)
+    double e2;                          ///< Polarization 1 (2Mxy)
+} psEllipsePol;
 
-psEllipsePol psEllipseAxesToPol(psEllipseAxes axes);
-psEllipsePol psEllipseShapeToPol(psEllipseShape shape);
-psErrorCode psEllipsePolToAxes(const psEllipsePol pol, const float minMinorAxis, psEllipseAxes *axes);
+// Conversions between elliptical shape representations
+
+/// Convert axes to moments representation
+psEllipseMoments psEllipseAxesToMoments(psEllipseAxes axes ///< Axes of ellipse
+                                        );
+
+/// Convert moments to axes representation
+psEllipseAxes psEllipseMomentsToAxes(psEllipseMoments moments, ///< Moments of ellipse
+                                     double maxAR ///< Maximum allowed axis ratio
+                                     );
+
+/// Convert axes to shape representation
+psEllipseShape psEllipseAxesToShape(psEllipseAxes axes ///< Axes of ellipse
+                                    );
+
+/// Convert shape to axes representation
+psEllipseAxes psEllipseShapeToAxes(psEllipseShape shape, ///< Shape of ellipse
+                                   double maxAR ///< Maximum allowed axis ratio
+                                   );
+
+/// Convert axes to polarisation representation
+psEllipsePol psEllipseAxesToPol(psEllipseAxes axes ///< Axes of ellipse
+                                );
+
+/// Convert shape to polarisation representation
+psEllipsePol psEllipseShapeToPol(psEllipseShape shape ///< Shape of ellipse
+                                 );
+
+/// Convert polarisation to axes representation
+///
+/// XXX This API goes against the PS convention of outputs being first.
+psErrorCode psEllipsePolToAxes(const psEllipsePol pol, ///< Polarisation of ellipse
+                               const float minMinorAxis, ///< Minimum allowed minor axis
+                               psEllipseAxes *axes ///< Output ellipse axes
+                               );
 
 /// @}