DM-9925: PolyTran should not provide an iterative inverse by default

doc/attributes_fitsChan.dox

@@ -138,7 +138,7 @@ The name of the keyword for the current card of the FitsChan. (string)
 @subsection FitsChan_CardType CardType
 
 The data type of the keyword value for the current card of the FitsChan
-as an @ref CardType enum.
+as a @ref CardType enum.
 
 
 @subsection FitsChan_CarLin CarLin

doc/mainpage.dox

@@ -36,9 +36,9 @@ that support time, spectra and tables have yet been wrapped. The python wrapper
         and @ref Mapping.over as a convient way to make a @ref ParallelMap.
     - Added @ref Frame.over as a convenient way to make a @ref CmpFrame.
     - Instead of wrapping `astDecompose`:
-        - Call @ref CmpMap.operator[] to retrieve a mapping from a compound mapping.
+        - Call CmpMap.operator[] to retrieve a mapping from a compound mapping.
         - Call @ref CmpMap.getSeries to find out if a compound mapping is in series.
-        - Call @ref CmpFrame.operator[] to retrieve a @ref Frame from a @ref CmpFrame
+        - Call CmpFrame.operator[] to retrieve a @ref Frame from a @ref CmpFrame
 - Exceptions are raised on errors, leaving AST in a normal (non-error) state:
     - Where practical, the wrapper checks arguments and throws `std::invalid_argument`
         before calling AST code.
@@ -72,6 +72,8 @@ that support time, spectra and tables have yet been wrapped. The python wrapper
         (implementing `astMapGet0<X>`, `astMapGet1<X>`, `astMapPut0<X>` and `astMapPut1<X>`).
     - Methods `append` and `replace` are used to alter values in existing entries
         (implementing `astMapPutElem...<X>`).
+- @ref PolyMap has two separate constructors, one that takes foward and inverse coefficients,
+    one that takes only forward coefficients. Neither provides an iterative inverse by default.
 
 ## Missing Functionality
 

include/astshim/Channel.h

@@ -171,7 +171,7 @@ friend class Object;
     */
     explicit Channel(AstChannel * chan);
 
-    Stream _stream;
+    Stream _stream;  ///< stream read and/or written read by the channel
 };
 
 }  // namespace ast

include/astshim/FitsChan.h

@@ -79,8 +79,8 @@ class FoundValue {
     FoundValue() :
         found(false), value()
     {}
-    bool found;
-    T value;
+    bool found;  ///< Was the value found?
+    T value;   ///< The found value; ignore if `found` is false
 };
 
 /**

include/astshim/Frame.h

@@ -38,45 +38,68 @@ class CmpFrame;
 class Frame;
 
 /**
-Struct returned by @ref Frame.offset2 containing a direction (an angle in radians) and a point
+Struct returned by @ref Frame.offset2 containing a direction and a point
 */
 class DirectionPoint {
 public:
+    /**
+    Construct a DirectionPoint
+
+    @param[in] direction  Direction, and angle in radians
+    @param[in] point  Point
+    */
     DirectionPoint(double direction, PointD const &point) : direction(direction), point(point){};
-    double direction;
-    PointD point;
+    double direction;  ///< Direction, an angle in radians
+    PointD point;  ///< Point
 };
 
 /**
 Struct returned by @ref Frame.unformat containing the number of characters read and corresponding value
 */
 class NReadValue {
 public:
+    /**
+    Construct an NReadValue
+
+    @param[in] nread  Number of characters that was read
+    @param[in] value  Value that was read
+    */
     NReadValue(int nread, double value) : nread(nread), value(value){};
-    int nread;
-    double value;
+    int nread;  ///< Number of characters that was read
+    double value;  ///< Value that was read
 };
 
 /**
 Struct returned by @ref Frame.resolve containing a point and the resolved vector components
 */
 class ResolvedPoint {
 public:
+    /**
+    Construct an empty ResolvedPoint
+
+    @param[in] naxes  Number of axes in the point
+    */
     explicit ResolvedPoint(int naxes) : point(naxes), d1(), d2() {}
-    std::vector<double> point;
-    double d1;
-    double d2;
+    std::vector<double> point;  ///< Point
+    double d1;  ///< Resolved vector component 1
+    double d2;  ///< Resolved vector component 2
 };
 
 /**
 Struct returned by @ref Frame.pickAxes containing a frame and a mapping
 */
 class FrameMapping {
 public:
+    /**
+    Construct a FrameMapping
+
+    @param[in,out] frame  Frame
+    @param[in,out] mapping  Mapping
+    */
     FrameMapping(std::shared_ptr<Frame> frame, std::shared_ptr<Mapping> mapping) :
      frame(frame), mapping(mapping) {}
-    std::shared_ptr<Frame> frame;
-    std::shared_ptr<Mapping> mapping;
+    std::shared_ptr<Frame> frame;  ///< Frame
+    std::shared_ptr<Mapping> mapping;  ///< Mapping
 };
 
 

include/astshim/FrameSet.h

@@ -102,6 +102,7 @@ friend class Object;
 public:
     static int constexpr BASE = AST__BASE;  ///< index of base frame
     static int constexpr CURRENT = AST__CURRENT;  ///< index of current frame
+    static int constexpr NOFRAME = AST__NOFRAME; ///< an invalid frame index
     /**
     Construct a FrameSet from a Frame
 
@@ -346,7 +347,7 @@ friend class Object;
        in the @ref FrameSet (as given by @ref getNframe).
        If `AST__NOFRAME` is supplied (or the current @ref Frame is specified),
        then any mirroring established by a previous call to this function is disabled.
-       A value of `FrameSet::BASE may be given to specify the base frame.
+       A value of FrameSet::BASE may be given to specify the base frame.
 
     ### Notes:
     - Mirrors can be chained. That is, if @ref Frame B is set to be a mirror

include/astshim/MapBox.h

@@ -36,20 +36,6 @@ class Mapping;
 Object to compute the bounding box which just encloses another box
 after it has been transformed by a mapping.
 
-Fields:
-- lbndIn  The lower bound specified by the user for each input coordinate
-- ubndIn  The upper bound specified by the user for each output coordinate
-- minOutCoord  The index of the first output coordinate (starting at 1)
-            over which the output box was computed.
-- maxOutCoord  The index of the last output coordinate (starting at 1)
-            over which the output box was computed.
-- lbndOut  The lower bound of the output box; the elements are for output coord
-            `minOutCoord` through `maxOutCoord`.
-- ubndOut  The upper bound of the output box; the elements are for output coord
-            `minOutCoord` through `maxOutCoord`.
-- xl  a 2-d array of [out coord, an input point at which the lower bound occurred]
-- xu  a 2-d array of [out coord, an input point at which the upper bound occurred]
-
 @warning  The points in `xl` and `xu` are not predictable if more than one input value
     gives the same output boundary value.
 */
@@ -72,7 +58,8 @@ class MapBox {
         an output bounding box, starting from 1
     @param[in] maxOutCoord  Maximum output coordinate axis for which to compute
         an output bounding box, starting from 1,
-        or 0 for all remaining output coordinate axes.
+        or 0 for all remaining output coordinate axes (in which case
+        the field of the same name will be set to the number of outputs)
 
     @return A @ref MapBox containing the computed outputs and a copy of the inputs.
 
@@ -104,16 +91,19 @@ class MapBox {
     MapBox & operator=(MapBox const &) = default;
     MapBox & operator=(MapBox &&) = default;
 
-    std::vector<double> lbndIn;
-    std::vector<double> ubndIn;
+    std::vector<double> lbndIn;  ///< Lower bound of the input box.
+    std::vector<double> ubndIn;  ///< Upper bound of the input box.
+    /// Minimum output coordinate axis for which to compute an output bounding box, starting from 1
     int minOutCoord;
+    /// Maximum output coordinate axis for which to compute an output bounding box, starting from 1
     int maxOutCoord;
-    std::vector<double> lbndOut;
-    std::vector<double> ubndOut;
-    Array2D xl;
-    Array2D xu;
+    std::vector<double> lbndOut;  ///< Lower bound of the output box.
+    std::vector<double> ubndOut;  ///< Upper bound of the output box.
+    Array2D xl;  ///< 2-d array of [out coord, an input point at which the lower bound occurred]
+    Array2D xu;  ///< 2-d array of [out coord, an input point at which the upper bound occurred]
 
 private:
+    /// Compute the outputs
     void _compute(Mapping const & map,
                   std::vector<double> const & lbnd,
                   std::vector<double> const & ubnd,

include/astshim/MapSplit.h

@@ -34,17 +34,6 @@ class Mapping;
 
 /**
 A Mapping split off as a subset of another Mapping.
-
-Fields:
-- splitMap:  Shared pointer to the split mapping.
-- origIn:  Indices of the inputs of the original mapping were picked for the split mapping
-        (a copy of the `in` argument of the constructor).
-- origOut:  Indices of the outputs of the original mapping which are fed by the picked inputs.
-        This will contain splitMap->getNout() elements, each in the range [1, nout of the original mapping].
-        The `i`th element holds the index within the original mapping which corresponds to
-        the `i`th output of the split mapping. For example if the 1st output of the split mapping
-        came from the 5th output of the original mapping, then origOut[0] = 5 (0 because
-        vectors use 0-based indexing, and 5 because AST index values are 1-based).
 */
 class MapSplit {
 public:
@@ -72,8 +61,25 @@ class MapSplit {
     MapSplit & operator=(MapSplit const &) = default;
     MapSplit & operator=(MapSplit &&) = default;
 
+    /**
+    The Mapping that was split off.
+    */
     std::shared_ptr<Mapping> splitMap;
+    /**
+    Indices of the inputs of the original mapping were picked for the split mapping
+
+    This is a copy of the `in` argument of the constructor.
+    */
     std::vector<int> origIn;
+    /**
+    Indices of the outputs of the original mapping which are fed by the picked inputs.
+
+    This will contain splitMap->getNout() elements, each in the range [1, nout of the original mapping].
+    The `i`th element holds the index within the original mapping which corresponds to
+    the `i`th output of the split mapping. For example if the 1st output of the split mapping
+    came from the 5th output of the original mapping, then origOut[0] = 5 (0 because
+    vectors use 0-based indexing, and 5 because AST index values are 1-based).
+    */
     std::vector<int> origOut;
 };
 

include/astshim/Mapping.h

@@ -126,11 +126,11 @@ friend class Object;
 
     An inverse mapping is a deep copy of a mapping whose @ref Mapping_Invert "Invert" attribute
     has been toggled, as indicated by @ref isInverted. This swaps the meaning of "input" and "output",
-    and of "forward" and "inverse". Thus it swaps the behavior of @ref tranForward and @refTranInverse,
-    @ref getNin and @ref getNout, @ref hasTranForward and @ref hasTranInverse and so on.
+    and of "forward" and "inverse". Thus it swaps the behavior of @ref tranForward and @ref tranInverse,
+    @ref getNin and @ref getNout, @ref hasForward and @ref hasInverse and so on.
 
     Note that the inverse mapping contains exactly the same model coefficients as the original,
-    but they are used by @tranInverse instead of @tranForward. Thus for example if a @ref ZoomMap
+    but they are used by @ref tranInverse instead of @ref tranForward. Thus for example if a @ref ZoomMap
     has a zoom factor of 4.0 then its inverse also reports a zoom factor of 4.0 (despite behaving
     like an uninverted @ref ZoomMap with zoom factor of 0.25).
     */

include/astshim/Object.h

@@ -52,7 +52,7 @@ friend class MapSplit;
     using Deleter = void (*)(AstObject *);
 
 public:
-    using ObjectPtr = std::unique_ptr<AstObject, Deleter>;
+    using ObjectPtr = std::unique_ptr<AstObject, Deleter>;  ///< unique pointer holding an AST raw pointer
 
     virtual ~Object() {}
 
@@ -255,10 +255,12 @@ friend class MapSplit;
 
     Intended for internal use only, but cannot be made protected
     without endless "friend class" declarations.
+    @{
     */
     AstObject const * getRawPtr() const { return &*_objPtr; };
 
     AstObject * getRawPtr() { return &*_objPtr; };
+    ///@}
 
 protected:
 
@@ -308,6 +310,18 @@ friend class MapSplit;
         return retptr;
     }
 
+    /**
+    Return a deep copy of this object. This is called by @ref copy.
+
+    Each subclass must override this method. The standard implementation is:
+    ```
+        return _copyImpl<astshim_class, ast_class>();
+    ```
+    for example @ref Frame implements this as:
+    ```
+        return _copyImpl<Frame, AstFrame>();
+    ```
+    */
     virtual std::shared_ptr<Object> _copyPolymorphic() const = 0;
 
     /**