basic documentation

jmeidow · jmeidow · commit 5faba5c9c557 · 2022-05-12T10:26:33.000+02:00
diff --git a/src/conics.cpp b/src/conics.cpp
@@ -32,6 +32,11 @@ using Eigen::Vector3d;
 using Eigen::Matrix2d;
 using Eigen::Matrix3d;
 
+ConicBase::ConicBase( const Matrix3d& other) : Matrix3d(other)
+{
+    // Q_ASSERT( isSymmetric()==true);
+    assert( isSymmetric()==true );
+}
 
 Matrix3d ConicBase::skew( const Vector3d &x) const
 {
diff --git a/src/conics.h b/src/conics.h
@@ -29,70 +29,68 @@ class uStraightLine;
 using Eigen::Matrix3d;
 using Eigen::Vector3d;
 
+//! Namespace Conic
 namespace Conic {
 
-
+//! Base class for conics
 class ConicBase : public Matrix3d
 {
 protected:
-    ConicBase() = default;
+    ConicBase() = default;                   //!< Standard constructor
     virtual ~ConicBase() = default;
 
 public:
-    ConicBase (const ConicBase &) = delete;
-    ConicBase ( ConicBase &&) = delete;
-    ConicBase & operator = ( const ConicBase &) = delete ;
-    ConicBase & operator= ( ConicBase &&) = delete;
-    ConicBase( const Matrix3d& other) : Matrix3d(other)  {
-        // Q_ASSERT( isSymmetric()==true);
-        assert( isSymmetric()==true );
-    }
-    ConicBase & operator= ( const Matrix3d & other);
-
-    bool isEllipse()   const;  // obsolete
-    bool isHyperbola() const;  // obsolete
-    bool isParabola()  const;  // obsolete
-    bool isCentral()   const;
-    bool isProper()    const;  // obsolete
-
-    Vector3d center() const;
-    Vector3d polar( const Vector3d & x ) const;
-    std::pair<Vector3d,Vector3d> intersect( const Vector3d & l ) const;
+    ConicBase (const ConicBase &) = delete;  //!< Copy constructor
+    ConicBase ( ConicBase &&) = delete;      //!< Move constructor
+    ConicBase & operator = ( const ConicBase &) = delete ;  //!< Copy assignment operator
+    ConicBase & operator= ( ConicBase &&) = delete;         //!< Move assignment operator
+    ConicBase( const Matrix3d & other);               //!< Value constructor
+    ConicBase & operator= ( const Matrix3d & other);  //!< Assignment operator
+
+    bool isEllipse()   const;  //!< Check if conic is an ellipse (not required)
+    bool isHyperbola() const;  //!< Check if conic is a hyperbola (not required)
+    bool isParabola()  const;  //!< Check if conic is a parabola (not required)
+    bool isCentral()   const;  //!< Check if conic has a central point
+    bool isProper()    const;  //!< Check if conic is non-degenerated
+
+    Vector3d center() const;   //!< Get center point of conic
+    Vector3d polar( const Vector3d & x ) const;                          //!< Compute polar l (straight line) for point x, i.e., l=C*x
+    std::pair<Vector3d,Vector3d> intersect( const Vector3d & l ) const;  //!< Two intersection points with a straight line
 
 protected:
-    void transform( const Matrix3d & HH );
-    Matrix3d cof3( const Matrix3d & MM ) const;   //!< 3x3 cofactor matrix
+    void transform( const Matrix3d & HH );        //!< Transformtion of conic according to x'=H*x
+    Matrix3d cof3( const Matrix3d & MM ) const;   //!< 3x3 cofactor matrix, i.e., transposed adjunct
 
 private:
     Matrix3d skew( const Vector3d & x ) const;
     bool isSymmetric() const;
 };
 
 
-
+//! Ellipse
 class Ellipse : public ConicBase
 {
 public:
-    Ellipse( const Uncertain::uPoint &ux, double k2=1.0 );
+    Ellipse( const Uncertain::uPoint &ux, double k2=1.0 ); //!< Value constructor (uncertain point)
 
-    std::pair<Eigen::VectorXd,Eigen::VectorXd> poly( int N ) const;
-    void scale( double s ); // obsolete
+    std::pair<Eigen::VectorXd,Eigen::VectorXd> poly( int N ) const;  //!< Get N points on ellipse
+    void scale( double s ); //!< Scale (enlarge, shrink) the ellipse (not required)
 
     using ConicBase::operator=;
 };
 
 
-
+//! Hyperbola
 class Hyperbola : public ConicBase
 {
 public:
-    Hyperbola( const Uncertain::uStraightLine &l, double k2=1.0 );
+    Hyperbola( const Uncertain::uStraightLine &l, double k2=1.0 ); //!< Value constructor (uncertain straight line)
     using ConicBase::operator=;
 
-    Vector3d centerline() const;
-    std::pair<double,double> lengthsSemiAxes() const;
-    double angle_rad() const;
-    double angle_deg() const;
+    Vector3d centerline() const;  //!< Get straight line
+    std::pair<double,double> lengthsSemiAxes() const;  //!< Get lengths/2 of axes
+    double angle_rad() const;     //!< Get angle between straight line and x-axis in radians.
+    double angle_deg() const;     //!< Get angle between straight line and x-axis in degerees.
 
 private:
     std::pair<double,double> eigenvalues() const;
