Add more documentation comments by iFlow CLI

Author: luk036

README.md

@@ -1,7 +1,7 @@
-[![Actions Status](https://github.com/luk036/ellalgo-cpp/workflows/MacOS/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
-[![Actions Status](https://github.com/luk036/ellalgo-cpp/workflows/Windows/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
-[![Actions Status](https://github.com/luk036/ellalgo-cpp/workflows/Ubuntu/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
-[![Actions Status](https://github.com/luk036/ellalgo-cpp/workflows/Install/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
+[![MacOS Build Status](https://github.com/luk036/ellalgo-cpp/workflows/MacOS/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
+[![Windows Build Status](https://github.com/luk036/ellalgo-cpp/workflows/Windows/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
+[![Ubuntu Build Status](https://github.com/luk036/ellalgo-cpp/workflows/Ubuntu/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
+[![Install Status](https://github.com/luk036/ellalgo-cpp/workflows/Install/badge.svg)](https://github.com/luk036/ellalgo-cpp/actions)
 [![codecov](https://codecov.io/gh/luk036/ellalgo-cpp/branch/master/graph/badge.svg)](https://codecov.io/gh/luk036/ellalgo-cpp)
 
 <p align="center">

documentation/CMakeLists.txt

@@ -24,6 +24,7 @@ configure_file(${CMAKE_CURRENT_LIST_DIR}/conf.py ${CMAKE_CURRENT_BINARY_DIR}/con
 add_custom_target(
   GenerateDocs
   ${CMAKE_COMMAND} -E make_directory "${DOXYGEN_OUTPUT_DIRECTORY}"
+  COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_LIST_DIR}/../ellalgo.svg" "${DOXYGEN_OUTPUT_DIRECTORY}/"
   COMMAND "${m.css_SOURCE_DIR}/documentation/doxygen.py" "${CMAKE_CURRENT_BINARY_DIR}/conf.py"
   COMMAND echo "Docs written to: ${DOXYGEN_OUTPUT_DIRECTORY}"
   WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"

documentation/Doxyfile

@@ -26,14 +26,4 @@ GENERATE_LATEX = NO
 XML_PROGRAMLISTING = NO
 CREATE_SUBDIRS = NO
 
-# Include all directories, files and namespaces in the documentation
-# Disable to include only explicitly documented objects
-# M_SHOW_UNDOCUMENTED = YES
 
-ALIASES += le="≤"
-ALIASES += kappa="κ"
-ALIASES += pi="π"
-ALIASES += omega="ω"
-ALIASES += forall="∀"
-ALIASES += in="∈"
-ALIASES += pm="±"

documentation/conf.py

@@ -1,8 +1,39 @@
-DOXYFILE = 'Doxyfile'
+import warnings
+import logging
+
+# Suppress Python deprecation warnings about testing element truth values
+warnings.filterwarnings(
+    "ignore",
+    category=DeprecationWarning,
+    message=".*Testing an element's truth value.*",
+)
+
+# Suppress warnings about external images not found in XML output
+warnings.filterwarnings(
+    "ignore", message=".*was not found in XML_OUTPUT", category=RuntimeWarning
+)
+warnings.filterwarnings(
+    "ignore", message=".*was not found in XML_OUTPUT", category=UserWarning
+)
+
+
+# Suppress the specific logging messages about external images in m.css
+class ImageNotFoundFilter(logging.Filter):
+    def filter(self, record):
+        # Suppress specific image not found messages
+        if "was not found in XML_OUTPUT" in record.getMessage():
+            return False
+        return True
+
+
+# Apply the filter to the root logger
+logging.getLogger().addFilter(ImageNotFoundFilter())
+
+DOXYFILE = "Doxyfile"
 
 LINKS_NAVBAR1 = [
-    (None, 'pages', [(None, 'about')]),
-    (None, 'namespaces', []),
+    (None, "pages", [(None, "about")]),
+    (None, "namespaces", []),
 ]
 
 # Add your own navbar links using the code below.

include/ellalgo/ell_assert.hpp

@@ -1,9 +1,44 @@
+/**
+ * @file ell_assert.hpp
+ * @brief Branch prediction macros for performance optimization
+ *
+ * This header provides macros for giving hints to the compiler about
+ * the likelihood of certain conditions being true or false. This can
+ * help the CPU generate more efficient code by optimizing branch
+ * prediction.
+ */
+
 #pragma once
 
+/**
+ * @def ELL_LIKELY
+ * @brief Hint that the expression is likely to be true
+ * 
+ * This macro tells the compiler that the expression is likely to evaluate
+ * to true, allowing it to optimize the generated code for the common case.
+ * 
+ * @param x The expression to evaluate
+ * @return The same expression value
+ */
 #if defined(__clang__) || defined(__GNUC__)
 #    define ELL_LIKELY(x) __builtin_expect(!!(x), 1)
-#    define ELL_UNLIKELY(x) __builtin_expect(!!(x), 0)
 #else
 #    define ELL_LIKELY(x) (!!(x))
+#endif
+
+/**
+ * @def ELL_UNLIKELY
+ * @brief Hint that the expression is unlikely to be true
+ * 
+ * This macro tells the compiler that the expression is unlikely to evaluate
+ * to true, allowing it to optimize the generated code for the uncommon case.
+ * This is typically used for error conditions or exceptional paths.
+ * 
+ * @param x The expression to evaluate
+ * @return The same expression value
+ */
+#if defined(__clang__) || defined(__GNUC__)
+#    define ELL_UNLIKELY(x) __builtin_expect(!!(x), 0)
+#else
 #    define ELL_UNLIKELY(x) (!!(x))
 #endif

include/ellalgo/ell_config.hpp

@@ -4,35 +4,92 @@
 #include <utility>  // for pair
 
 /**
- * @brief Options
+ * @brief Configuration options for the ellipsoid algorithm
  *
+ * This structure contains the configuration parameters for controlling
+ * the behavior of the ellipsoid algorithm, including maximum iterations
+ * and convergence tolerance.
  */
 struct Options {
-    size_t max_iters;
-    double tolerance;
+    size_t max_iters;  ///< Maximum number of iterations allowed
+    double tolerance;  ///< Convergence tolerance for stopping criteria
 
+    /**
+     * @brief Default constructor
+     * 
+     * Initializes with default values: max_iters = 2000, tolerance = 1e-20
+     */
     Options() : max_iters{2000}, tolerance{1e-20} {}
+    
+    /**
+     * @brief Constructor with custom parameters
+     * 
+     * @param[in] max_iters Maximum number of iterations
+     * @param[in] tol Convergence tolerance
+     */
     Options(size_t max_iters, double tol) : max_iters{max_iters}, tolerance{tol} {}
 };
 
 /**
- * @brief Cut Status
+ * @brief Status of cutting plane operations
  *
+ * This enumeration represents the possible outcomes of cutting plane
+ * operations in the ellipsoid algorithm.
  */
-enum class CutStatus { Success, NoSoln, NoEffect, Unknown };
+enum class CutStatus { 
+    Success,   ///< Cut was successful and ellipsoid was updated
+    NoSoln,    ///< No solution exists (infeasible)
+    NoEffect,  ///< Cut had no effect on ellipsoid
+    Unknown    ///< Unknown status
+};
 
 /**
- * @brief CInfo
+ * @brief Information about the computation result
  *
+ * This structure contains information about the computation,
+ * including feasibility status and number of iterations used.
  */
 struct CInfo {
-    bool feasible;
-    size_t num_iters;
+    bool feasible;      ///< Whether a feasible solution was found
+    size_t num_iters;   ///< Number of iterations performed
 };
 
+/**
+ * @brief Type alias for the array type used by template parameter T
+ * 
+ * This type alias extracts the ArrayType nested type from template parameter T.
+ * 
+ * @tparam T The type containing ArrayType
+ */
 template <typename T> using ArrayType = typename T::ArrayType;
+
+/**
+ * @brief Type alias for the cut choice type used by template parameter T
+ * 
+ * This type alias extracts the CutChoice nested type from template parameter T.
+ * 
+ * @tparam T The type containing CutChoice
+ */
 template <typename T> using CutChoice = typename T::CutChoice;
+
+/**
+ * @brief Type alias for a cutting plane concept
+ * 
+ * This type alias defines a pair of array and cut choice, representing
+ * a cutting plane in the algorithm.
+ * 
+ * @tparam T The template parameter type
+ */
 template <typename T> using CutConcept = std::pair<ArrayType<T>, CutChoice<T>>;
+
+/**
+ * @brief Type alias for return type of Q optimization
+ * 
+ * This type alias defines the return type for Q optimization functions,
+ * containing cut concept, boolean flags, and array data.
+ * 
+ * @tparam T The template parameter type
+ */
 template <typename T> using RetQ = std::tuple<CutConcept<T>, bool, ArrayType<T>, bool>;
 
 #if __cpp_concepts >= 201907L

include/ellalgo/ell_matrix.hpp

@@ -97,11 +97,11 @@ class Matrix {
      * This performs an element-wise multiplication of the matrix by the scalar value alpha.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix *= 2.0
-     * >>> matrix
-     * valarray([0., 0., 0., 0., 0., 0., 0., 0., 0.],
-     *          [3])
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix *= 2.0;
+     * // matrix becomes valarray([0., 0., 0., 0., 0., 0., 0., 0., 0.], [3])
+     * @endcode
      *
      * @param[in] alpha - The scalar value to multiply the matrix by.
      * @return A new Matrix object containing the result of the multiplication.
@@ -116,11 +116,11 @@ class Matrix {
      * all diagonal elements to 1.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix.identity()
-     * >>> matrix
-     * valarray([1., 0., 0., 0., 1., 0., 0., 0., 1.],
-     *          [3])
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix.identity();
+     * // matrix becomes valarray([1., 0., 0., 0., 1., 0., 0., 0., 1.], [3])
+     * @endcode
      */
     void identity() {
         this->clear();
@@ -134,12 +134,13 @@ class Matrix {
      * where row index equals column index, corresponding to the diagonal.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix(0, 0) = 1.0
-     * >>> matrix(1, 1) = 2.0
-     * >>> matrix(2, 2) = 3.0
-     * >>> matrix.diagonal()
-     * valarray([1., 2., 3.], 3)
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix(0, 0) = 1.0;
+     * matrix(1, 1) = 2.0;
+     * matrix(2, 2) = 3.0;
+     * // matrix.diagonal() returns valarray([1., 2., 3.], 3)
+     * @endcode
      *
      * @return View of the diagonal elements as a slice_array.
      */
@@ -152,12 +153,13 @@ class Matrix {
      * where row index + column index equals ndim-1, corresponding to the secondary diagonal.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix(0, 0) = 1.0
-     * >>> matrix(1, 1) = 2.0
-     * >>> matrix(2, 2) = 3.0
-     * >>> matrix.secondary_diagonal()
-     * valarray([0., 0.], 2)
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix(0, 0) = 1.0;
+     * matrix(1, 1) = 2.0;
+     * matrix(2, 2) = 3.0;
+     * // matrix.secondary_diagonal() returns valarray([0., 0.], 2)
+     * @endcode
      *
      * @return View of the secondary diagonal elements as a slice_array.
      */
@@ -172,16 +174,15 @@ class Matrix {
      * of the specified row index.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix(0, 0) = 1.0
-     * >>> matrix(1, 1) = 2.0
-     * >>> matrix(2, 2) = 3.0
-     * >>> matrix.row(0)
-     * valarray([1., 0., 0.], 3)
-     * >>> matrix.row(1)
-     * valarray([0., 2., 0.], 3)
-     * >>> matrix.row(2)
-     * valarray([0., 0., 3.], 3)
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix(0, 0) = 1.0;
+     * matrix(1, 1) = 2.0;
+     * matrix(2, 2) = 3.0;
+     * // matrix.row(0) returns valarray([1., 0., 0.], 3)
+     * // matrix.row(1) returns valarray([0., 2., 0.], 3)
+     * // matrix.row(2) returns valarray([0., 0., 3.], 3)
+     * @endcode
      *
      * @param[in] row - The index of the row to extract.
      * @return View of the row elements as a slice_array.
@@ -197,16 +198,15 @@ class Matrix {
      * of the specified column index.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix(0, 0) = 1.0
-     * >>> matrix(1, 1) = 2.0
-     * >>> matrix(2, 2) = 3.0
-     * >>> matrix.column(0)
-     * valarray([1., 0., 0.], 3)
-     * >>> matrix.column(1)
-     * valarray([0., 2., 0.], 3)
-     * >>> matrix.column(2)
-     * valarray([0., 0., 3.], 3)
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix(0, 0) = 1.0;
+     * matrix(1, 1) = 2.0;
+     * matrix(2, 2) = 3.0;
+     * // matrix.column(0) returns valarray([1., 0., 0.], 3)
+     * // matrix.column(1) returns valarray([0., 2., 0.], 3)
+     * // matrix.column(2) returns valarray([0., 0., 3.], 3)
+     * @endcode
      *
      * @param[in] col - The index of the column to extract.
      * @return View of the column elements as a slice_array.
@@ -222,12 +222,13 @@ class Matrix {
      * elements, and then summing those elements.
      *
      * Example:
-     * >>> matrix = Matrix(3, 0.0)
-     * >>> matrix(0, 0) = 1.0
-     * >>> matrix(1, 1) = 2.0
-     * >>> matrix(2, 2) = 3.0
-     * >>> matrix.trace()
-     * 6.0
+     * @code{.cpp}
+     * Matrix matrix(3, 0.0);
+     * matrix(0, 0) = 1.0;
+     * matrix(1, 1) = 2.0;
+     * matrix(2, 2) = 3.0;
+     * // matrix.trace() returns 6.0
+     * @endcode
      *
      * @return The trace of the matrix as a double.
      */