Add doxygen-compliant documentation based on the MATLAB docs.

include/dqrobotics/internal/_dq_linesegment.h

@@ -31,32 +31,112 @@ namespace DQ_robotics
 namespace internal
 {
 
+/**
+ * @brief Internal routines for closest-feature queries between line segments.
+ *
+ * This class supports the line-segment distance algorithms used inside the C++
+ * implementation of DQ Robotics. It is declared in the internal namespace and
+ * is not part of the stable public API.
+ *
+ * @internal
+ */
 class LineSegment
 {
 public:
+    /**
+     * @brief Identifies which primitive of a line segment participates in a closest pair.
+     */
     enum class Element{
-        Line,P1,P2
+        /** @brief The supporting infinite line of the segment. */
+        Line,
+        /** @brief The first endpoint of the segment. */
+        P1,
+        /** @brief The second endpoint of the segment. */
+        P2
     };
 
+    /**
+     * @brief Groups the supporting line and the two endpoints of a line segment.
+     */
     using Primitives = std::tuple<DQ,DQ,DQ>;
+
+    /**
+     * @brief Stores the closest primitive selected from each of two line segments.
+     */
     using ClosestElements = std::tuple<Element,Element>;
+
+    /**
+     * @brief Stores a closest-element pair together with its squared distance.
+     */
     using ClosestElementsAndDistance = std::tuple<ClosestElements, double>;
 
+    /**
+     * @brief Determines the closest primitives between two line segments.
+     *
+     * The algorithm compares admissible line-line, line-endpoint, and
+     * endpoint-endpoint candidates, discarding infeasible line-to-point cases,
+     * and returns the valid pair with minimum squared distance.
+     *
+     * @param line_1_primitives A tuple `(line, point_1, point_2)` describing the first segment.
+     * @param line_2_primitives A tuple `(line, point_1, point_2)` describing the second segment.
+     * @return A tuple containing the closest primitive pair and the corresponding squared distance.
+     */
     static ClosestElementsAndDistance closest_elements_between_line_segments(const Primitives& line_1_primitives,
                                                                              const Primitives& line_2_primitives);
 
 
+    /**
+     * @brief Tests whether a point lies strictly inside a line segment.
+     *
+     * This check compares the squared distances from the point to each endpoint
+     * against the segment squared length. It assumes the point already belongs to
+     * the supporting line; the collinearity test is not performed here.
+     *
+     * @param point The point to be tested.
+     * @param line_1_primitives A tuple `(line, point_1, point_2)` describing the segment.
+     * @return `true` if the point lies strictly between the endpoints and `false` otherwise.
+     * @note Endpoints are considered outside because strict inequalities are used.
+     */
     static bool is_inside_line_segment(const DQ &point, const Primitives &line_1_primitives);
 
+    /**
+     * @brief Converts an Element enumerator to its string representation.
+     *
+     * @param e The enumerator to be converted.
+     * @return The string representation of `e`.
+     * @throws std::runtime_error If `e` does not match a known enumerator.
+     */
     static std::string to_string(const Element& e);
 
 
 private:
 
+    /**
+     * @brief Selects the best valid closest-pair candidate seen so far.
+     *
+     * Invalid candidates are represented with `NaN` distances and are ignored.
+     * When both candidates are valid, the one with smaller squared distance is
+     * returned.
+     *
+     * @param current The current best result.
+     * @param candidate The new candidate to be compared against `current`.
+     * @return The preferred result after the comparison.
+     */
     static ClosestElementsAndDistance _update_closest_pair(
             const ClosestElementsAndDistance& current,
             const ClosestElementsAndDistance& candidate);
 
+    /**
+     * @brief Evaluates a line-to-point candidate for the line-segment search.
+     *
+     * The method projects the point onto the supporting line of the segment. If
+     * the projection lies inside the segment, it returns the squared point-to-line
+     * distance; otherwise, it returns `NaN` to mark the candidate as infeasible.
+     *
+     * @param line_segment A tuple `(line, point_1, point_2)` describing the segment.
+     * @param point The point from the other segment.
+     * @return The squared point-to-line distance for a feasible candidate, or `NaN` otherwise.
+     */
     static double _line_to_point_feasibility_and_distance(
             const Primitives& line_segment,
             const DQ& point);

include/dqrobotics/robot_control/DQ_ClassicQPController.h

@@ -28,17 +28,53 @@ This file is part of DQ Robotics.
 namespace DQ_robotics
 {
 
+/**
+ * @brief Implements the classic quadratic-programming kinematic controller based on task-space variables.
+ *
+ * This controller uses a quadratic objective built from the task Jacobian and the
+ * Euclidean task-space error. Its default isotropic damping is initialized to 1e-3.
+ *
+ * @see DQ_QuadraticProgrammingController, DQ_PseudoinverseController
+ */
 class DQ_ClassicQPController:public DQ_QuadraticProgrammingController
 {
 public:
     DQ_ClassicQPController() = delete;
 
     //Deprecated
+    /**
+     * @brief Constructs a classic QP controller from legacy raw pointers.
+     *
+     * @param robot Non-owning pointer to the robot kinematic model.
+     * @param solver Non-owning pointer to the quadratic-programming solver.
+     */
     DQ_ClassicQPController(DQ_Kinematics* robot, DQ_QuadraticProgrammingSolver* solver);
+    /**
+     * @brief Constructs a classic QP controller from shared pointers.
+     *
+     * @param robot Shared pointer to the robot kinematic model.
+     * @param solver Shared pointer to the quadratic-programming solver.
+     */
     DQ_ClassicQPController(const std::shared_ptr<DQ_Kinematics>& robot,
                            const std::shared_ptr<DQ_QuadraticProgrammingSolver>& solver);
 
+    /**
+     * @brief Computes the symmetric matrix H used in the quadratic objective.
+     *
+     * The returned matrix corresponds to J'J plus isotropic damping. The second
+     * argument of the abstract interface is unused by this controller.
+     *
+     * @param J Task Jacobian associated with the current control objective.
+     * @return The symmetric matrix H of the quadratic objective.
+     */
     MatrixXd compute_objective_function_symmetric_matrix(const MatrixXd& J, const VectorXd&) override;
+    /**
+     * @brief Computes the linear vector f used in the quadratic objective.
+     *
+     * @param J Task Jacobian associated with the current control objective.
+     * @param task_error Current task-space error.
+     * @return The linear component f of the quadratic objective.
+     */
     VectorXd compute_objective_function_linear_component(const MatrixXd& J, const VectorXd& task_error) override;
 };
 

include/dqrobotics/robot_control/DQ_KinematicConstrainedController.h

@@ -32,22 +32,71 @@ using namespace Eigen;
 namespace DQ_robotics
 {
 
+/**
+ * @brief Abstract superclass used to define concrete kinematic controllers with algebraic constraints.
+ *
+ * This class extends DQ_KinematicController with equality and inequality constraints
+ * on the control input. Constrained controllers can store matrices and vectors that
+ * are later supplied to optimization-based control laws.
+ *
+ * @see DQ_KinematicController, DQ_QuadraticProgrammingController
+ */
 class DQ_KinematicConstrainedController: public DQ_KinematicController
 {
 protected:
+    /** @brief Matrix used in equality constraints of the form Aeq*u = beq. */
     MatrixXd equality_constraint_matrix_;
+    /** @brief Vector used in equality constraints of the form Aeq*u = beq. */
     VectorXd equality_constraint_vector_;
+    /** @brief Matrix used in inequality constraints of the form A*u <= b. */
     MatrixXd inequality_constraint_matrix_;
+    /** @brief Vector used in inequality constraints of the form A*u <= b. */
     VectorXd inequality_constraint_vector_;
 
+    /**
+     * @brief Constructs a constrained controller from a legacy raw robot pointer.
+     *
+     * @param robot Non-owning pointer to the robot kinematic model.
+     */
     [[deprecated("Use the smart pointer version instead")]]
     DQ_KinematicConstrainedController(DQ_Kinematics* robot);
+    /**
+     * @brief Constructs a constrained controller from a shared robot pointer.
+     *
+     * @param robot Shared pointer to the robot kinematic model.
+     */
     DQ_KinematicConstrainedController(const std::shared_ptr<DQ_Kinematics>& robot);
 public:
     //Remove default constructor
     DQ_KinematicConstrainedController()=delete;
 
+    /**
+     * @brief Sets the equality constraint passed to constrained control laws.
+     *
+     * Defines the equality constraint B*u = b, where u is the control input
+     * computed by the constrained control law.
+     *
+     * @note This constraint is not persistent: it is stored as-is and reused on every
+     * subsequent call to the control law until overwritten. To keep enforcing it,
+     * call this method again before each control-signal computation.
+     *
+     * @param B Equality-constraint matrix.
+     * @param b Equality-constraint vector.
+     */
     virtual void set_equality_constraint(const MatrixXd& B, const VectorXd& b);
+    /**
+     * @brief Sets the inequality constraint passed to constrained control laws.
+     *
+     * Defines the inequality constraint B*u <= b, where u is the control input
+     * computed by the constrained control law.
+     *
+     * @note This constraint is not persistent: it is stored as-is and reused on every
+     * subsequent call to the control law until overwritten. To keep enforcing it,
+     * call this method again before each control-signal computation.
+     *
+     * @param B Inequality-constraint matrix.
+     * @param b Inequality-constraint vector.
+     */
     virtual void set_inequality_constraint(const MatrixXd& B, const VectorXd& b);
 
 };