merged #21 doxygenization branch into #134, and harmonized the docs f…

…or the Shear class. Ellipse is still not well documented though, and I should make some minor changes to the shear.py module to reflect use here.

include/galsim/Shear.h

@@ -1,12 +1,13 @@
+// -*- c++ -*-
+#ifndef SHEAR_H
+#define SHEAR_H
 /**
  * @file Shear.h Contains a class definition for Shear and Ellipse.
  *
  * Shear is used to represent shape distortions; Ellipse includes shear, translation and
  * magnification.
 */
 
-#ifndef SHEAR_H
-#define SHEAR_H
 #include <cmath>
 #include "TMV.h"
 
@@ -30,17 +31,22 @@ namespace galsim {
      * intrinsic shapes, and due to lensing shears.  Given semi-major and semi-minor axis lengths
      * "a" and "b", there are numerous ways to represent shears:
      *
-     * eta = "conformal shear", a/b = exp(eta)
-     * g = "reduced shear", g=(a-b)/(a+b)
-     * e = "distortion", e=(a^2-b^2)/(a^2+b^2)
-     * q = "axis ratio", q=b/a
-     * To specify both components, we have a value Beta that is the
-     * real-space position angle of the major axis, i.e. e1 = e cos(2*Beta) and e2 = e sin(2*Beta).
+     * eta = "conformal shear", a/b = exp(|eta|)
+     *
+     * g   = "reduced shear", |g| = (a-b)/(a+b)
+     *
+     * e   = "distortion", |e| = (a^2-b^2)/(a^2+b^2)
+     *
+     * q   = "axis ratio", |q|=b/a
+     * 
+     * To specify both components, we have a value Beta that is the real-space position angle of 
+     * the major axis, i.e. e1 = e cos(2*Beta) and e2 = e sin(2*Beta).
      *
      * Shears are represented internally by e1 and e2, which relate to second moments via
-     * e1 = (Mxx - Myy) / (Mxx + Myy)
-     * e2 = 2 Mxy / (Mxx + Myy)
-     * however, given that lensing specialists most commonly think in terms of reduced shear, the
+     * e1 = (Mxx - Myy) / (Mxx + Myy),
+     * e2 = 2 Mxy / (Mxx + Myy).
+     *
+     * However, given that lensing specialists most commonly think in terms of reduced shear, the
      * constructor that takes two numbers expects (g1, g2).  A user who wishes to specify another
      * type of shape should use methods, i.e.
      *     s = Shear();
@@ -52,16 +58,23 @@ namespace galsim {
         friend Shear operator*(const double, const Shear& );
 
     public:
-        // Construct w/o variance
+        /** 
+         * @brief Construct without variance / without initializing transformation matrix.
+         *
+         * @param[in] g1 first component (reduced shear definition).
+         * @param[in] g2 second shear component (reduced shear definition).
+         */
         explicit Shear(double g1=0., double g2=0.) :
             hasMatrix(false), matrixA(0), matrixB(0), matrixC(0)
                 { setG1G2(g1, g2); }
 
+        /// @brief Copy constructor.
         Shear(const Shear& rhs) :
             e1(rhs.e1), e2(rhs.e2), hasMatrix(rhs.hasMatrix),
             matrixA(rhs.matrixA), matrixB(rhs.matrixB), matrixC(rhs.matrixC) 
         {}
 
+        /// @brief Copy assignment.
         const Shear& operator=(const Shear& s)
         {
             e1 = s.e1; e2=s.e2;
@@ -70,74 +83,162 @@ namespace galsim {
             return *this;
         }
 
+        /// @brief Set (e1, e2) using distortion definition.
         Shear& setE1E2(double e1in=0., double e2in=0.);
+
+        /** 
+         * @brief Set (|e|, beta) polar ellipticity representation using distortion definition.
+         * beta must be an Angle.
+         */
         Shear& setEBeta(double etain=0., Angle betain=Angle());
+
+        /// @brief Set (eta1, eta2) using conformal shear definition.
         Shear& setEta1Eta2(double eta1in=0., double eta2in=0.);
-        Shear& setEtaBeta(double etain=0., Angle betain=Angle());
+
+        /// @brief Set (|eta|, beta) using conformal shear definition. beta must be an Angle.
+        Shear& setEtaBeta(double =0., Angle betain=Angle());
+
+        /// @brief set (g1, g2) using reduced shear |g| = (a-b)/(a+b) definition.
         Shear& setG1G2(double g1in=0., double g2in=0.);
 
+        /// @brief Get e1 using distortion definition.
         double getE1() const { return e1; }
+
+        /// @brief Get e2 using distortion definition.
         double getE2() const { return e2; }
+
+        /// @brief Get |e| using distortion definition.
         double getE() const { return std::sqrt(e1*e1+e2*e2); }
+
+        /// @brief Get |e|^2 using distortion definition.
         double getESq() const { return e1*e1+e2*e2; }
+
+        /// @brief Get polar angle beta (returns an Angle class object).
         Angle getBeta() const { return std::atan2(e2,e1)*0.5 * radians; }
+
+        /// @brief Get |eta| using conformal shear definition.
         double getEta() const { return atanh(std::sqrt(e1*e1+e2*e2)); } //error checking?
 
-        // g = gamma / (1-kappa)
+        /// @brief Get |g| using reduced shear |g| = (a-b)/(a+b) definition.
         double getG() const 
         {
             double e=getE();  
             return e>0. ? (1-std::sqrt(1-e*e))/e : 0.;
         }
+
+        /// @brief Get g1 using reduced shear |g| = (a-b)/(a+b) definition.
         double getG1() const
         {
             double esq = getESq();
             double scale = (esq>1.e-6) ? (1.-std::sqrt(1.-esq))/esq : 0.5;
             return e1*scale;
         }
+
+        /// @brief Get g1 using reduced shear |g| = (a-b)/(a+b) definition.
         double getG2() const
         {
             double esq = getESq();
             double scale = (esq>1.e-6) ? (1.-std::sqrt(1.-esq))/esq : 0.5;
             return e2*scale;
         }
 
+        /**
+         * @brief Get (eta1, eta2) using conformal shear definition.
+         *
+         * @param[in,out] eta1 Reference to eta1 variable.
+         * @param[in,out] eta2 Reference to eta2 variable.
+         *
+         */
         void getEta1Eta2(double& eta1, double& eta2) const;
+
+        /**
+         * @brief Get (g1, g2) using reduced shear |g| = (a-b)/(a+b) definition.
+         *
+         * @param[in,out] g1 Reference to g1 variable.
+         * @param[in,out] g2 Reference to g2 variable.
+         *
+         */
         void getG1G2(double& g1, double& g2) const;
 
-
-        //negation
+        /// @brief Unary negation (both components negated).
         Shear operator-() const 
         {
             double esq = getESq();
             double scale = (esq>1.e-6) ? (1.-std::sqrt(1.-esq))/esq : 0.5;
             return esq>0. ? Shear(-e1*scale, -e2*scale) : Shear(0.0, 0.0);
         }
 
-        // Composition operation: returns ellipticity of
-        // circle that is sheared first by RHS and then by
-        // LHS Shear.  Note that this addition is
-        // ***not commutative***!
-        // In the += and -= operations, this is LHS
-        // and the operand is RHS of + or - .
+        /**
+         * @brief Composition operation.
+         *
+         * Note that this 'addition' is ***not commutative***!
+         *
+         * @returns Ellipticity of circle that is sheared first by RHS and then by
+         * LHS Shear.  
+         */
         Shear operator+(const Shear& ) const;
+
+        /**
+         * @brief Composition (with RHS negation) operation.
+         *
+         * Note that this 'subtraction' is ***not commutative***!
+         *
+         * @returns Ellipticity of circle that is sheared first by the negative RHS and then by
+         * LHS Shear.
+         */ 
         Shear operator-(const Shear& ) const;
+
+        // In the += and -= operations, this is LHS
+        // and the operand is RHS of + or - .
+
+        /**
+         * @brief Inplace composition operation. 
+         *
+         * Note that this 'addition' is ***not commutative***!
+         *
+         * In the += operation, this is LHS and the operand is RHS of +.
+         *
+         * @returns Ellipticity of circle that is sheared first by RHS and then by
+         * LHS Shear. 
+         */
         Shear& operator+=(const Shear& );
+
+        /**
+         * @brief Inplace composition (with RHS negation) operation.
+         *
+         * Note that this 'addition' is ***not commutative***!
+         *
+         * In the -= operation, this is LHS and the operand is RHS of -.
+         *
+         * @returns Ellipticity of circle that is sheared first by the negative RHS and then by
+         * LHS Shear.
+         */
         Shear& operator-=(const Shear& );
 
-        // Give the rotation angle for this+rhs:
-        Angle rotationWith(const Shear& rhs) const;
-        // Detail on the above: s1 + s2 operation on points in
-        // the plane induces a rotation as well as a shear.
-        // Above method tells you what the rotation was for LHS+RHS
+        /** @brief Give the rotation angle for this+rhs.
+         *
+         * Detail on the above: s1 + s2 operation on points in
+         * the plane induces a rotation as well as a shear.
+         * Above method tells you what the rotation was for LHS+RHS.
+         */
+        Angle rotationWith(const Shear& rhs) const; 
 
+        ///@brief Test equivalence by comparing e1 and e2.
         bool operator==(const Shear& rhs) const 
         { return e1==rhs.e1 && e2==rhs.e2; }
 
+        ///@brief Test non-equivalence by comparing e1 and e2.
         bool operator!=(const Shear& rhs) const 
         { return e1!=rhs.e1 || e2!=rhs.e2; }
 
-        // Classes that treat shear as a point-set map:
+        // Classes thattreat shear as a point-set map:
+        /**
+         * @brief Forward transformation from image to source plane coordinates under shear.
+         *
+         * @param[in] p  2D vector Position in image plane.
+         *
+         * @returns      2D vector Position in source plane.
+         */
         template <class T>
         Position<T> fwd(Position<T> p) const 
         {
@@ -147,6 +248,13 @@ namespace galsim {
             return out;
         }
 
+        /**
+         * @brief Inverse transformation from source to image plane coordinates under shear.
+         *
+         * @param[in] p  2D vector Position in source plane.
+         *
+         * @returns      2D vector Position in image plane.
+         */
         template <class T>
         Position<T> inv(Position<T> p) const 
         {
@@ -156,10 +264,13 @@ namespace galsim {
             return out;
         }
 
-        // Get matrix representation of the forward transformation.
-        // Matrix is   ... and in limit of small shear:
-        // (  a   c     =    (  1+g1  g2
-        //    c   b )            g2  1-g1 )
+        /**
+         * @brief Get matrix representation of the forward transformation.
+         *
+         * Matrix is   ... and in limit of small shear:
+         *  ( a   c     =    ( 1+g1  g2
+         *    c   b )            g2  1-g1 )
+         */
         void getMatrix(double& a, double& b, double& c) const 
         { calcMatrix(); a=matrixA; b=matrixB; c=matrixC; }