Add Doxygen documentation

- Add documentation for C++ API functions.
- Add matrix data sanity check to ensure uniform rows.

Author: ZCG-coder

doxygen-awesome-css

@@ -36,8 +36,8 @@
 #pragma once
 
 #include "fn/root.hpp"
-#include "steppable/number.hpp"
 #include "output.hpp"
+#include "steppable/number.hpp"
 #include "types/result.hpp"
 
 #include <string>
@@ -46,8 +46,8 @@
 using namespace std::literals;
 
 /**
- * @namespace steppable::__internals
- * @brief The namespace containing internal functions for the Steppable library.
+ * @namespace steppable::__internals::calc
+ * @brief The namespace containing number calculating functions for the Steppable library.
  */
 namespace steppable::__internals::calc
 {

include/fn/calc.hpp

@@ -24,6 +24,10 @@
 
 #include <string>
 
+/**
+ * @namespace steppable::__internals
+ * @brief The namespace containing internal functions for the Steppable library.
+ */
 namespace steppable::__internals::calc
 {
     /**

include/fn/root.hpp

@@ -77,8 +77,25 @@ namespace steppable
         size_t prec = 10; ///< Precision of numbers in the matrix.
         MatVec2D<Number> data; ///< The data of the matrix.
 
+        /**
+         * @brief Checks whether a point is inside the matrix. Errors and exits the program if not.
+         * @param point The point to check.
+         */
         void _checkIdxSanity(const YXPoint* point) const;
 
+        /**
+         * @brief Checks whether the matrix data is correct in format.
+         * @details This method checks for non-uniform rows inside the matrix.
+         *
+         * @param data The matrix data vector.
+         */
+        static void _checkDataSanity(const MatVec2D<Number>& data);
+
+        /**
+         * @brief Rounds off all data inside a vector to a specified precision.
+         * @param data A double `std::vector` object containing matrix data.
+         * @param prec Precision of the matrix.
+         */
         static MatVec2D<Number> roundOffValues(const MatVec2D<Number>& data, size_t prec);
 
     public:
@@ -109,6 +126,12 @@ namespace steppable
          */
         Matrix(const MatVec2D<Number>& data, size_t prec = 5);
 
+        /**
+         * @brief Constructs a matrix from a 2D vector of C++ numbers.
+         * @param data The 2D vector representing the matrix data.
+         * @param prec Precision of the numbers.
+         * @tparam ValueT Type of value in the `data` parameter.
+         */
         template<concepts::Numeric ValueT>
         Matrix(const MatVec2D<ValueT>& data, const size_t prec) :
             _cols(data.front().size()), _rows(data.size()), prec(prec)
@@ -428,6 +451,10 @@ namespace steppable
          */
         [[nodiscard]] size_t getCols() const { return _cols; }
 
+        /**
+         * @brief Get the data std::vector object from the matrix.
+         * @return A std::vector object containing all the matrix data.
+         */
         [[nodiscard]] MatVec2D<Number> getData() const { return data; }
     };
 } // namespace steppable

include/steppable/mat2d.hpp

@@ -67,9 +67,9 @@ namespace steppable
 
     enum class Rounding : std::uint8_t
     {
-        ROUND_DOWN = 0x00,
-        ROUND_UP = 0x01,
-        ROUND_OFF = 0x02,
+        ROUND_DOWN = 0x00, ///< Rounds the number down.
+        ROUND_UP = 0x01, ///< Rounds the number up.
+        ROUND_OFF = 0x02, ///< Rounds the number off.
     };
 
     /**
@@ -309,7 +309,7 @@ namespace steppable
     };
 
     /**
-     * @namespace literals
+     * @namespace steppable::literals
      * @brief Literal suffixes for literals to be converted to Steppable objects.
      */
     namespace literals

include/steppable/number.hpp

@@ -36,9 +36,10 @@
 namespace steppable::concepts
 {
     template<typename T>
-    concept Numeric = std::integral<T> || std::floating_point<T>;
+    concept Numeric = std::integral<T> || std::floating_point<T>; ///< Represents any C++ numeral literals.
 
     template<typename ObjectT>
+    /// @brief Represents any object with a `.present()` method.
     concept Presentable = requires(ObjectT object) {
         { object.present() } -> std::same_as<std::string>;
     };

include/types/concepts.hpp

@@ -60,13 +60,13 @@ namespace steppable
 
     enum class _Weekday : std::uint8_t
     {
-        Sunday = 0,
-        Monday = 1,
-        Tuesday = 2,
-        Wednesday = 3,
-        Thursday = 4,
-        Friday = 5,
-        Saturday = 6,
+        Sunday = 0, ///< Sunday
+        Monday = 1, ///< Monday
+        Tuesday = 2, ///< Tuesday
+        Wednesday = 3, ///< Wednesday
+        Thursday = 4, ///< Thursday
+        Friday = 5, ///< Friday
+        Saturday = 6, ///< Saturday
     };
 
     using Weekday = Data<_Weekday, StringLiteral{ "Weekday" }>;

include/types/data.hpp

@@ -31,8 +31,8 @@ namespace steppable
      */
     struct XYPoint
     {
-        size_t x = 0;
-        size_t y = 0;
+        size_t x = 0; ///< Coordinate x.
+        size_t y = 0; ///< Coordinate y.
     };
 
     /**
@@ -42,8 +42,8 @@ namespace steppable
      */
     struct YXPoint
     {
-        size_t y = 0;
-        size_t x = 0;
+        size_t y = 0; ///< Coordinate y.
+        size_t x = 0; ///< Coordinate x.
     };
 
     /**
@@ -53,9 +53,9 @@ namespace steppable
      */
     struct YX2Points
     {
-        size_t y1 = 0;
-        size_t x1 = 0;
-        size_t y2 = 0;
-        size_t x2 = 0;
+        size_t y1 = 0; ///< Point 1 coordinate y.
+        size_t x1 = 0; ///< Point 1 coordinate x.
+        size_t y2 = 0; ///< Point 2 coordinate y.
+        size_t x2 = 0; ///< Point 2 coordinate x.
     };
 } // namespace steppable

include/types/point.hpp

@@ -44,21 +44,21 @@ namespace steppable::types
      */
     enum class Status : std::uint8_t
     {
-        CALCULATED_SIMPLIFIED,
-        CALCULATED_UNSIMPLIFIED,
-        MATH_ERROR
+        CALCULATED_SIMPLIFIED, ///< The calculation is done by taking simplified steps.
+        CALCULATED_UNSIMPLIFIED, ///< The calculation is done.
+        MATH_ERROR ///< The calculation is not done because of an error.
     };
 
     /**
      * @brief The status of a boolean calculation.
      */
     enum class StatusBool : std::uint8_t
     {
-        CALCULATED_SIMPLIFIED_YES,
-        CALCULATED_SIMPLIFIED_NO,
-        CALCULATED_UNSIMPLIFIED_YES,
-        CALCULATED_UNSIMPLIFIED_NO,
-        MATH_ERROR
+        CALCULATED_SIMPLIFIED_YES, ///< The calculation is done by taking simplified steps, the result it True.
+        CALCULATED_SIMPLIFIED_NO, ///< The calculation is done by taking simplified steps, the result it False.
+        CALCULATED_UNSIMPLIFIED_YES, ///< The calculation is done, the result it True.
+        CALCULATED_UNSIMPLIFIED_NO, ///< The calculation is done, the result it False.
+        MATH_ERROR ///< The calculation is not done because of an error.
     };
 
     /**

include/types/result.hpp

@@ -98,12 +98,28 @@ namespace steppable
         }
     } // namespace prettyPrint::printers
 
+    void Matrix::_checkDataSanity(const MatVec2D<Number>& data)
+    {
+        size_t size = 0;
+        for (const auto& row : data)
+        {
+            const size_t rowSize = row.size();
+            if (rowSize != size)
+            {
+                output::error("Matrix::_checkDataSanity"s, "Matrix has non-uniform dimensions."s);
+                utils::programSafeExit(1);
+            }
+            size = rowSize;
+        }
+    }
+
     Matrix::Matrix() : data({ {} }) { _cols = _rows = 0; }
 
     Matrix::Matrix(const size_t rows, const size_t cols, const Number& fill) :
         data(std::vector(rows, std::vector(cols, fill))), _cols(cols), _rows(rows)
     {
         data = roundOffValues(data, static_cast<int>(prec));
+        _checkDataSanity(data);
     }
 
     Matrix::Matrix(const MatVec2D<Number>& data, const size_t prec) :