more docs and format alignment

Author: SpectraL519

Doxyfile

@@ -199,7 +199,7 @@ STRIP_FROM_PATH        =
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    =
+STRIP_FROM_INC_PATH    = include/
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't

include/gl/decl/impl_tags.hpp

@@ -2,6 +2,9 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file gl/decl/impl_tags.hpp
+/// @brief Forward declares implementation tags for different graph representations.
+
 #pragma once
 
 #include "gl/traits.hpp"
@@ -22,6 +25,19 @@ struct flat_matrix_t;
 
 namespace traits {
 
+/// @ingroup GL GL-Traits
+/// @brief Validates if a type is one of the defined graph implementation tags.
+///
+/// This concept is used to constrain template parameters that are expected to be
+/// specific graph implementation tags, ensuring type safety and clear intent in template usage.
+///
+/// The valid tags include:
+/// - @ref gl::impl::list_t "impl::list_t": Represents a standard adjacency list implementation.
+/// - @ref gl::impl::flat_list_t "impl::flat_list_t": Represents a flattened adjacency list implementation.
+/// - @ref gl::impl::matrix_t "impl::matrix_t": Represents a standard adjacency matrix implementation.
+/// - @ref gl::impl::flat_matrix_t "impl::flat_matrix_t": Represents a flattened adjacency matrix implementation.
+///
+/// @tparam T The type to evaluate against the concept.
 template <typename T>
 concept c_graph_impl_tag =
     c_one_of<T, impl::list_t, impl::flat_list_t, impl::matrix_t, impl::flat_matrix_t>;

include/gl/graph_traits.hpp

@@ -2,33 +2,89 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file gl/graph_traits.hpp
+/// @brief Defines the primary graph traits structure and related type aliases for different graph configurations.
+
 #pragma once
 
 #include "gl/decl/graph_traits.hpp"
 #include "gl/decl/impl_tags.hpp"
+#include "gl/directional_tags.hpp"
 #include "gl/edge_descriptor.hpp"
 #include "gl/types/core.hpp"
 
 namespace gl {
 
+/// @ingroup GL GL-Core
+/// @brief Primary graph traits structure that encapsulates all necessary type information for graph implementations.
+///
+/// This structure serves as the central point for defining the properties and types associated with a graph,
+/// including directionality, vertex and edge properties, as well as implementation and identifier types. It is designed
+/// to be flexible and extensible, allowing users to customize their graph types by specifying different traits.
+///
+/// ### Template Parameters
+/// | Parameter        | Description | Default value | Constraints |
+/// | :--------------- | :---------- | :------------ | :---------- |
+/// | DirectionalTag   | Specifies whether the graph is directed or undirected. | @ref gl::directed_t "directed_t" | [**c_graph_directional_tag**](gl_traits.md#gl-traits-c-graph-directional-tag) |
+/// | VertexProperties | A type representing the properties associated with vertices in the graph. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_traits.md#gl-traits-c-properties) |
+/// | EdgeProperties   | A type representing the properties associated with edges in the graph. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_traits.md#gl-traits-c-properties) |
+/// | ImplTag          | Specifies the graph implementation type (e.g., adjacency list, adjacency matrix). | @ref gl::impl::list_t "impl::list_t" | [**c_graph_impl_tag**](gl_traits.md#gl-traits-c-graph-impl-tag) |
+/// | IdType           | The type used for vertex and edge identifiers. | @ref gl::default_id_type "default_id_type" | [**c_id_type**](gl_traits.md#gl-traits-c-id-type) |
+///
+/// ### See Also
+/// - Available implementation tags:
+///   - @ref gl::impl::list_t "impl::list_t" : A standard adjacency list implementation.
+///   - @ref gl::impl::flat_list_t "impl::flat_list_t" : A flattened adjacency list implementation.
+///   - @ref gl::impl::matrix_t "impl::matrix_t" : A standard adjacency matrix implementation.
+///   - @ref gl::impl::flat_matrix_t "impl::flat_matrix_t" : A flattened adjacency matrix implementation.
+/// - @ref gl::directed_t "directed_t", @ref gl::undirected_t "undirected_t" : For the directional tags used to specify graph directionality.
+/// - @ref gl::vertex_descriptor "vertex_descriptor" : For the vertex descriptor type defined based on the graph traits.
+/// - @ref gl::edge_descriptor "edge_descriptor" : For the edge descriptor type defined based on the graph traits.
+/// - @ref gl::empty_properties "empty_properties" : For the default empty properties type used when no custom properties are needed.
+/// - Convenience type aliases for the `graph_traits` type:
+///   - @ref gl::list_graph_traits "list_graph_traits",
+///   - @ref gl::flat_list_graph_traits "flat_list_graph_traits",
+///   - @ref gl::matrix_graph_traits "matrix_graph_traits",
+///   - @ref gl::flat_matrix_graph_traits "flat_matrix_graph_traits",
+///   - @ref gl::directed_graph_traits "directed_graph_traits",
+///   - @ref gl::undirected_graph_traits "undirected_graph_traits"
 template <
     traits::c_graph_directional_tag DirectionalTag = directed_t,
     traits::c_properties VertexProperties = empty_properties,
     traits::c_properties EdgeProperties = empty_properties,
     traits::c_graph_impl_tag ImplTag = impl::list_t,
     traits::c_id_type IdType = default_id_type>
 struct graph_traits {
+    /// @brief The tag indicating the graph's directionality (directed or undirected).
     using directional_tag = DirectionalTag;
+    /// @brief The tag indicating the graph's implementation type (e.g., adjacency list, adjacency matrix).
     using implementation_tag = ImplTag;
+    /// @brief The type of graph element indentifiers (i.e. vertex and edge IDs).
     using id_type = IdType;
 
+    /// @brief The vertex descriptor type associated with this graph, defined based on the specified vertex properties and identifier type.
     using vertex_type = vertex_descriptor<VertexProperties, id_type>;
+    /// @brief The type of properties associated with the vertex descriptor.
     using vertex_properties_type = typename vertex_type::properties_type;
 
+    /// @brief The edge descriptor type associated with this graph, defined based on the specified edge properties and identifier type.
     using edge_type = edge_descriptor<DirectionalTag, EdgeProperties, id_type>;
+    /// @brief The type of properties associated with the edge descriptor.
     using edge_properties_type = typename edge_type::properties_type;
 };
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for graph traits with an adjacency list implementation.
+///
+/// This alias simplifies the specification of graph traits for graphs that use an adjacency list representation,
+/// allowing users to easily define their graph types with the desired properties and directionality while defaulting
+/// to the adjacency list implementation.
+///
+/// > [!NOTE] Template parameters
+/// >
+/// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the
+/// > `ImplTag` parameter fixed to @ref gl::impl::list_t "impl::list_t". This means that when using `list_graph_traits`,
+/// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified.
 template <
     traits::c_graph_directional_tag DirectionalTag = directed_t,
     traits::c_properties VertexProperties = empty_properties,
@@ -37,6 +93,18 @@ template <
 using list_graph_traits =
     graph_traits<DirectionalTag, VertexProperties, EdgeProperties, impl::list_t, IdType>;
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for graph traits with a flattened adjacency list implementation.
+///
+/// This alias simplifies the specification of graph traits for graphs that use a flattened adjacency list representation,
+/// allowing users to easily define their graph types with the desired properties and directionality while defaulting
+/// to the flattened adjacency list implementation.
+///
+/// > [!NOTE] Template parameters
+/// >
+/// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the
+/// > `ImplTag` parameter fixed to @ref gl::impl::flat_list_t "impl::flat_list_t". This means that when using `flat_list_graph_traits`,
+/// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified.
 template <
     traits::c_graph_directional_tag DirectionalTag = directed_t,
     traits::c_properties VertexProperties = empty_properties,
@@ -45,6 +113,18 @@ template <
 using flat_list_graph_traits =
     graph_traits<DirectionalTag, VertexProperties, EdgeProperties, impl::flat_list_t, IdType>;
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for graph traits with an adjacency matrix implementation.
+///
+/// This alias simplifies the specification of graph traits for graphs that use an adjacency matrix representation,
+/// allowing users to easily define their graph types with the desired properties and directionality while defaulting
+/// to the adjacency matrix implementation.
+///
+/// > [!NOTE] Template parameters
+/// >
+/// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the
+/// > `ImplTag` parameter fixed to @ref gl::impl::matrix_t "impl::matrix_t". This means that when using `matrix_graph_traits`,
+/// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified.
 template <
     traits::c_graph_directional_tag DirectionalTag = directed_t,
     traits::c_properties VertexProperties = empty_properties,
@@ -53,6 +133,18 @@ template <
 using matrix_graph_traits =
     graph_traits<DirectionalTag, VertexProperties, EdgeProperties, impl::matrix_t, IdType>;
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for graph traits with a flattened adjacency matrix implementation.
+///
+/// This alias simplifies the specification of graph traits for graphs that use a flattened adjacency matrix representation,
+/// allowing users to easily define their graph types with the desired properties and directionality while defaulting
+/// to the flattened adjacency matrix implementation.
+///
+/// > [!NOTE] Template parameters
+/// >
+/// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the
+/// > `ImplTag` parameter fixed to @ref gl::impl::flat_matrix_t "impl::flat_matrix_t". This means that when using `flat_matrix_graph_traits`,
+/// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified.
 template <
     traits::c_graph_directional_tag DirectionalTag = directed_t,
     traits::c_properties VertexProperties = empty_properties,
@@ -61,6 +153,16 @@ template <
 using flat_matrix_graph_traits =
     graph_traits<DirectionalTag, VertexProperties, EdgeProperties, impl::flat_matrix_t, IdType>;
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for graph traits with an directed graph configuration.
+///
+/// This alias simplifies the specification of graph traits for directed graphs, allowing users to easily define their
+/// graph types with the desired properties and implementation while defaulting to a directed configuration.
+///
+/// > [!NOTE] Template parameters
+/// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the
+/// > `DirectionalTag` parameter fixed to @ref gl::directed_t "directed_t". This means that when using `directed_graph_traits`,
+/// > only the `VertexProperties`, `EdgeProperties`, 'ImplTag', and `IdType` parameters need to be specified.
 template <
     traits::c_properties VertexProperties = empty_properties,
     traits::c_properties EdgeProperties = empty_properties,
@@ -69,6 +171,16 @@ template <
 using directed_graph_traits =
     graph_traits<directed_t, VertexProperties, EdgeProperties, ImplTag, IdType>;
 
+/// @ingroup GL GL-Core
+/// @brief Type alias for graph traits with an undirected graph configuration.
+///
+/// This alias simplifies the specification of graph traits for undirected graphs, allowing users to easily define their
+/// graph types with the desired properties and implementation while defaulting to an undirected configuration.
+///
+/// > [!NOTE] Template parameters
+/// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the
+/// > `DirectionalTag` parameter fixed to @ref gl::undirected_t "undirected_t". This means that when using `undirected_graph_traits`,
+/// > only the `VertexProperties`, `EdgeProperties`, 'ImplTag', and `IdType` parameters need to be specified.
 template <
     traits::c_properties VertexProperties = empty_properties,
     traits::c_properties EdgeProperties = empty_properties,
@@ -79,39 +191,63 @@ using undirected_graph_traits =
 
 namespace traits {
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a list implementation.
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_list_graph_traits =
     c_instantiation_of<TraitsType, graph_traits>
     and std::same_as<typename TraitsType::implementation_tag, impl::list_t>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a flattened adjacency list implementation.
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_flat_list_graph_traits =
     c_instantiation_of<TraitsType, graph_traits>
     and std::same_as<typename TraitsType::implementation_tag, impl::flat_list_t>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with an adjacency list implementation (either standard or flattened).
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_adjacency_list_graph_traits =
     c_list_graph_traits<TraitsType> or c_flat_list_graph_traits<TraitsType>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a matrix implementation.
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_matrix_graph_traits =
     c_instantiation_of<TraitsType, graph_traits>
     and std::same_as<typename TraitsType::implementation_tag, impl::matrix_t>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a flattened adjacency matrix implementation.
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_flat_matrix_graph_traits =
     c_instantiation_of<TraitsType, graph_traits>
     and std::same_as<typename TraitsType::implementation_tag, impl::flat_matrix_t>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a matrix implementation (either standard or flattened).
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_adjacency_matrix_graph_traits =
     c_matrix_graph_traits<TraitsType> or c_flat_matrix_graph_traits<TraitsType>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a directed graph configuration.
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_directed_graph_traits =
     c_instantiation_of<TraitsType, graph_traits>
     and std::same_as<typename TraitsType::directional_tag, directed_t>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with an undirected graph configuration.
+/// @tparam TraitsType The type to evaluate against the concept.
 template <typename TraitsType>
 concept c_undirected_graph_traits =
     c_instantiation_of<TraitsType, graph_traits>

include/gl/impl/impl_tags.hpp

@@ -2,6 +2,9 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file gl/impl/impl_tags.hpp
+/// @brief Defines implementation tags for different graph representations.
+
 #pragma once
 
 #include "gl/decl/impl_tags.hpp"
@@ -10,25 +13,49 @@
 
 namespace gl::impl {
 
+/// @ingroup GL GL-Core
+/// @headerfile gl/impl/impl_tags.hpp
+/// @brief Tag struct for the standard adjacency list graph implementation.
 struct list_t {
+    /// @brief Type alias for the adjacency list graph implementation based on the provided graph traits.
+    /// @tparam GraphTraits The graph traits for which to define the adjacency list type.
+    ///         Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `list_t` as its implementation tag.
     template <traits::c_instantiation_of<graph_traits> GraphTraits>
     requires(std::same_as<typename GraphTraits::implementation_tag, list_t>)
     using type = adjacency_list<GraphTraits>;
 };
 
+/// @ingroup GL GL-Core
+/// @headerfile gl/impl/impl_tags.hpp
+/// @brief Tag struct for the flattened adjacency list graph implementation.
 struct flat_list_t {
+    /// @brief Type alias for the flattened adjacency list graph implementation based on the provided graph traits.
+    /// @tparam GraphTraits The graph traits for which to define the flattened adjacency list type.
+    ///         Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `flat_list_t` as its implementation tag.
     template <traits::c_instantiation_of<graph_traits> GraphTraits>
     requires(std::same_as<typename GraphTraits::implementation_tag, flat_list_t>)
     using type = adjacency_list<GraphTraits>;
 };
 
+/// @ingroup GL GL-Core
+/// @headerfile gl/impl/impl_tags.hpp
+/// @brief Tag struct for the standard adjacency matrix graph implementation.
 struct matrix_t {
+    /// @brief Type alias for the adjacency matrix graph implementation based on the provided graph traits.
+    /// @tparam GraphTraits The graph traits for which to define the adjacency matrix type.
+    ///         Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `matrix_t` as its implementation tag.
     template <traits::c_instantiation_of<graph_traits> GraphTraits>
     requires(std::same_as<typename GraphTraits::implementation_tag, matrix_t>)
     using type = adjacency_matrix<GraphTraits>;
 };
 
+/// @ingroup GL GL-Core
+/// @headerfile gl/impl/impl_tags.hpp
+/// @brief Tag struct for the flattened adjacency matrix graph implementation.
 struct flat_matrix_t {
+    /// @brief Type alias for the flattened adjacency matrix graph implementation based on the provided graph traits.
+    /// @tparam GraphTraits The graph traits for which to define the flattened adjacency matrix type.
+    ///         Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `flat_matrix_t` as its implementation tag.
     template <traits::c_instantiation_of<graph_traits> GraphTraits>
     requires(std::same_as<typename GraphTraits::implementation_tag, flat_matrix_t>)
     using type = adjacency_matrix<GraphTraits>;