This project uses Doxygen to generate documentation from annotated source code. Doxygen comments are used to describe the purpose, behavior, and usage of classes, functions, and other entities in the codebase. Follow these guidelines to ensure your code is well-documented and easy to understand. Always use @ for Doxygen commands.
All commands must start with @.
Useful Commands:
@file <name>@authors <authors>@ingroup <group-name>@defgroup <name> <group-title>@namespace <name>@class <name>@struct <name>@enum <name>@brief <brief description>@details <detailed description>@param[<direction>] <parameter-name> <parameter-description>@tparam <template-parameter-name> <description>@return <description>@throws <exception-object> <description>@note <text>@bug <description>@see <reference>@copyright <text>@cite <reference>@ref <reference> <display-text>
The following Doxygen aliases are defined in the Doxyfile to simplify common documentation tasks:
@math{<math expression>}@unitr{<unit expression>}@unitb{<unit expression>}@unitp{<unit expression>}@formula{<label>; <equation>}@symtable@symrow{<symbol>; <description>; <unit expression>}@endsymtable
When documenting code, use Doxygen comments to describe the purpose and behavior of classes, functions, and other entities. Follow these guidelines to ensure your documentation is clear, consistent, and useful.
Use the @math{<math expression>} command to to write LaTeX-style mathematical expressions in your documentation.
/**
* The speed of light in water is often denoted as @math{C_w}.
*/Use the @unitb{<unit expression>} command to document units. The @unitb{} command uses the siunitx package to format units in LaTeX style and encloses them in brackets.
/**
* The speed of light in water is often denoted as @math{C_w} and is approximately 2.25 @unitb{\meter\per\second}.
*/Use the @formula{<label>; <equation>} command to document formulas. The command takes 2 arguments, separated by ;:
- A label for the formula, which can be used to reference the formula in the documentation by using
\eqref{eq:<formula-label>}.- All labels are automatically prefixed with
eq:to avoid conflicts.
- All labels are automatically prefixed with
- The formula itself, written in LaTeX syntax.
/**
* The area of a circle can be computed using the formula:
* @formula{circle-area; A = \pi r^2}
*/
/**
* Remember to use \eqref{eq:circle-area} to calculate the area of a circle.
*/Use the @symtable and @endsymtable commands to create a table of symbols used in formulas. Each symbol is documented using the @symrow{<symbol>; <description>; <unit expression>} command, which takes three arguments, separated by ;:
- The symbol itself, written in LaTeX syntax.
- A description of the symbol.
- The unit of the symbol, written in LaTeX syntax and formatted using the siunitx package.
/**
* The area of a circle can be computed using the formula:
* @formula{circle-area; A = \pi r^2}
* where:
* @symtable
* @symrow{A; is the area of the circle; \meter\squared}
* @symrow{\pi; is the mathematical constant pi; 1}
* @symrow{r; is the radius of the circle; \meter}
* @endsymtable
*/Use a Doxygen block at the very top of each header file to document the file's purpose, authors, and any relevant notes.
@ingroup@file@authors@brief@details@note@see@copyright
/**
* @ingroup geometry
* @file polygon.h
* @authors Alice Brown, Carlos Diaz
* @brief Defines the Polygon class for representing simple 2-D polygons.
* @details This file contains the Polygon class, which provides methods for adding vertices, computing area, and checking point containment.
* @note The Polygon class assumes vertices are provided in counter-clockwise order.
* @see https://en.wikipedia.org/wiki/Polygon
* @copyright 2025 Geometry Toolkit
*/Use a Doxygen block above each namespace declaration in header files to document the namespace's purpose and contents.
@ingroup@namespace@brief@details@note@see
/**
* @ingroup math
* @namespace constants
* @brief Defines mathematical constants used throughout the project.
*/
namespace constants {}Use a Doxygen block above each class or struct declaration in header files to document its purpose, behavior, and any important details. This applies to both classes and structs.
@ingroup@class@struct@brief@details@tparam@note@bug@see
/**
* @ingroup geometry
* @struct Point2
* @brief Lightweight 2-D point with double precision.
*/
struct Point2 {
double x {0.0}; ///< X coordinate
double y {0.0}; ///< Y coordinate
};
/**
* @ingroup geometry
* @class Polygon
* @brief Simple 2-D polygon representation.
* @details Stores vertices in counter-clockwise order.
* @note Capacity is fixed at construction.
* @bug AddVertex does not check for self-intersection.
*/
class Polygon {
public:
/**
* @brief Constructs a Polygon with a maximum number of vertices.
* @param[in] max_vertices Maximum number of vertices allowed.
* @throws std::length_error If max_vertices is zero.
*/
Polygon(std::size_t max_vertices);
/**
* @brief Adds a vertex to the polygon.
* @param[in] p New vertex in world coordinates.
* @return Index of the inserted vertex.
* @throws std::length_error If max_vertices reached.
*/
std::size_t Polygon::addVertex(const Point2& p);
/**
* @brief Computes the signed area of the polygon.
* @details Uses the Shoelace formula to compute the area:
* @formula{polygon-area; A = \frac{1}{2} \sum_{i=1}^{n} (x_i y_{i+1} - x_{i+1} y_i)}
* where:
* @symtable
* @symrow{A; is the signed area of the polygon; \meter\squared}
* @symrow{n; is the number of vertices; 1}
* @symrow{x_i, y_i; are the coordinates of vertex i; \meter}
* @symrow{x_{n+1}, y_{n+1}; are the coordinates of vertex 1 (wrap-around); \meter}
* @endsymtable
* @note The area is positive if vertices are in counter-clockwise order.
* @return The signed area of the polygon.
*/
double area() const;
private:
std::vector<Point2> vertices_; ///< Vertices in counter-clockwise order.
};Use a Doxygen block above each public function or method declaration in header files. This applies to both free functions and member functions of classes or structs.
@brief@param[in]orparam[out]orparam[in,out]@return@details@tparam@throws@note@bug@see
/**
* @brief Adds a vertex to the polygon.
* @param[in] p New vertex in world coordinates.
* @return Index of the inserted vertex.
* @throws std::length_error If max_vertices reached.
*/
std::size_t Polygon::addVertex(const Point2& p);Use inline comments with ///< for one-line descriptions of data members. This applies to both classes and structs.
std::vector<Point2> vertices_; ///< Vertices in counter-clockwise order.Use inline comments with ///< to document constants and their purpose.
constexpr double kPi = 3.141592653589793; ///< Circle ratio @unitb{radians}.
inline constexpr Point2 kOrigin {0.0, 0.0}; ///< Reference point (0,0).Use a Doxygen block above each enum declaration in header files to document the enum type and its enumerators. Each enumerator should have an inline comment describing its purpose.
@ingroup@enum@brief@details@note@bug@see
/**
* @ingroup geometry
* @enum Axis
* @brief Principal 3-D axes.
*/
enum class Axis {
kX, ///< X-axis
kY, ///< Y-axis
kZ ///< Z-axis
};Use Doxygen groups to organize related namespaces, classes, and functions into logical modules.
Large groups must be defined in their own file (e.g., math.dox, geometry.dox) to avoid cluttering header files. These files should be placed in the docs/ directory or one of its subdirectories.
@defgroupingroup@brief@details@copydoc@see
/**
* @defgroup geometry Geometry
* @ingroup math
* @brief Geometry module for 2D and 3D shapes.
*/Use the Doxyfile to configure Doxygen settings like input/output directories, file patterns, and more.
Use the DoxygenLayout.xml file to customize the layout of the generated documentation.
To generate the documentation, follow these steps:
- Ensure Doxygen is installed.
- From the project root, run:
doxygen Doxyfile
- The generated HTML and/or LaTeX documentation will appear in the output directory specified in the
Doxyfile.