alg core doc

Author: SpectraL519

include/hgl/algorithm/core.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 hgl/algorithm/core.hpp
+/// @brief Core data structures and types used to control and track hypergraph algorithm execution.
+
 #pragma once
 
 #include "gl/algorithm/core.hpp"
@@ -20,50 +23,107 @@ namespace algorithm {
 
 // -- GL core ---
 
-using gl::algorithm::empty_callback;
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::empty_callback
+/// @see gl::algorithm::empty_callback for a more detailed description.
+using empty_callback = gl::algorithm::empty_callback;
 
-using gl::algorithm::decision;
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::decision
+/// @see gl::algorithm::decision for the full type definition
+using decision = gl::algorithm::decision;
 
-using gl::algorithm::result_discriminator;
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::result_discriminator
+/// @see gl::algorithm::result_discriminator for the full type definition.
+using result_discriminator = gl::algorithm::result_discriminator;
 using enum result_discriminator;
 
-using gl::algorithm::non_void_result_type;
-using gl::algorithm::result_type;
-
-using gl::algorithm::no_root;
-using gl::algorithm::no_root_t;
-using gl::algorithm::no_root_v;
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::result_type
+/// @see gl::algorithm::result_type for the full type definition.
+template <result_discriminator Result, typename ResultType>
+using result_type = gl::algorithm::result_type<Result, ResultType>;
+
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::non_void_result_type
+/// @see gl::algorithm::non_void_result_type for the full type definition.
+template <result_discriminator Result, typename ResultType>
+using non_void_result_type = gl::algorithm::non_void_result_type<Result, ResultType>;
+
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::no_root_v
+/// @see gl::algorithm::no_root_v
+template <traits::c_id_type IdType>
+inline constexpr IdType no_root_v = gl::algorithm::no_root_v<IdType>;
+
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::no_root_t
+/// @see gl::algorithm::no_root_t
+using no_root_t = gl::algorithm::no_root_t;
+
+/// @ingroup HGL-Algorithm
+/// @copybrief gl::algorithm::no_root
+/// @see gl::algorithm::no_root
+inline constexpr no_root_t no_root = gl::algorithm::no_root;
 
 // --- traversal types ---
 
+/// @ingroup HGL-Algorithm
+/// @brief Represents an active node in a search container (e.g., a BFS queue or DFS stack) for hypergraph traversals.
+/// @tparam H The type of the hypergraph being searched. Must satisfy [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph).
 template <traits::c_hypergraph H>
 struct search_node {
+    /// @brief The identifier type of the hypergraph elements.
     using id_type = typename H::id_type;
 
+    /// @brief Default constructor creates an invalid node.
     search_node() = default;
 
+    /// @brief Constructs a *root* search node (predecessor is itself, no incident hyperedge).
+    /// @param vertex_id The ID of the root vertex.
     search_node(id_type vertex_id)
     : vertex_id(vertex_id), pred_id(vertex_id), hyperedge_id(invalid_id) {}
 
+    /// @brief Constructs a search node with an explicit predecessor vertex and the connecting hyperedge.
+    /// @param vertex_id The ID of the currently reached vertex.
+    /// @param pred_id The ID of the predecessor vertex from which this vertex was reached.
+    /// @param hyperedge_id The ID of the hyperedge connecting the predecessor to this vertex.
     search_node(id_type vertex_id, id_type pred_id, id_type hyperedge_id)
     : vertex_id(vertex_id), pred_id(pred_id), hyperedge_id(hyperedge_id) {}
 
+    /// @brief Checks if this node is the root of a search tree.
+    /// @return `true` if the node is valid and its predecessor is itself, `false` otherwise.
     [[nodiscard]] gl_attr_force_inline bool is_root() const noexcept {
         return this->vertex_id != invalid_id and this->vertex_id == this->pred_id;
     }
 
+    /// @brief The ID of the current vertex.
     id_type vertex_id = invalid_id;
+    /// @brief The ID of the predecessor from which this vertex was reached.
     id_type pred_id = invalid_id;
+    /// @brief The ID of the hyperedge via which this vertex was reached from the predecessor.
     id_type hyperedge_id = invalid_id;
 };
 
+/// @ingroup HGL-Algorithm
+/// @brief A flat, index-mapped representation of a hypergraph search tree.
+///
+/// The $i$-th element corresponds to the vertex with `id == i`. The tree topology is formed implicitly,
+/// as each @ref hgl::algorithm::search_node "search_node" stores the ID of its predecessor and the
+/// connecting hyperedge, enabling $O(1)$ lookups and and $O(\vert V \vert)$ path reconstruction.
+///
+/// @tparam H The type of the hypergraph being searched.
 template <traits::c_hypergraph H>
 using search_tree = std::vector<search_node<H>>;
 
 } // namespace algorithm
 
 namespace traits {
 
+/// @ingroup HGL-Traits
+/// @brief Validates if a type is a valid hypergraph search tree (a random access range of @ref hgl::algorithm::search_node "search_node"s).
+/// @tparam T The type to evaluate against the concept.
 template <typename T>
 concept c_search_tree =
     c_random_access_range<T>
@@ -75,39 +135,70 @@ namespace algorithm {
 
 // --- generic algorithm traits ---
 
-enum class traversal_direction : bool { forward, backward };
+/// @ingroup HGL-Algorithm
+/// @brief Specifies the direction of traversal for *BF-directed* hypergraphs.
+///
+/// > [!IMPORTANT] API Simplicity
+/// >
+/// > To ensure API simplicity, the `traversal_direction` is used for undirected hypergraphs as well by
+/// > the generic traversal templates. However, due to the structural nature of undirected hypergraphs,
+/// > both direction values implicitly yield the exact same traversal pattern for undirected hypergraphs.
+enum class traversal_direction : bool {
+    forward, ///< Traverse following the forward star (tail to head).
+    backward ///< Traverse following the backward star (head to tail).
+};
 
+/// @ingroup HGL-Algorithm
+/// @brief Policy defining how to extract incident hyperedges and target vertices during traversal.
+///
+/// This template is specialized based on the hypergraph's directionality to route standard
+/// traversal algorithms over the correct incidence structures (e.g., following tails to heads).
+///
+/// @tparam H The type of the hypergraph.
+/// @tparam Dir The direction of traversal.
 template <traits::c_hypergraph H, traversal_direction Dir>
 struct traversal_policy;
 
+/// @ingroup HGL-Algorithm
+/// @brief Traversal policy specialization for undirected hypergraphs.
 template <traits::c_undirected_hypergraph H, traversal_direction Dir>
 struct traversal_policy<H, Dir> {
+    /// @brief Retrieves the hyperedges incident to the given vertex.
     static auto target_hyperedges(const H& h, typename H::id_type v_id) {
         return h.incident_hyperedge_ids(v_id);
     }
 
+    /// @brief Retrieves the vertices incident to the given hyperedge.
     static auto target_vertices(const H& h, typename H::id_type he_id) {
         return h.incident_vertex_ids(he_id);
     }
 };
 
+/// @ingroup HGL-Algorithm
+/// @brief Traversal policy specialization for forward searches on BF-directed hypergraphs.
 template <traits::c_bf_directed_hypergraph H>
 struct traversal_policy<H, traversal_direction::forward> {
+    /// @brief Retrieves the hyperedges originating from the given vertex (forward star).
     static auto target_hyperedges(const H& h, typename H::id_type v_id) {
         return h.out_hyperedge_ids(v_id); // forward star
     }
 
+    /// @brief Retrieves the vertices targeted by the given hyperedge (head nodes).
     static auto target_vertices(const H& h, typename H::id_type he_id) {
         return h.head_ids(he_id);
     }
 };
 
+/// @ingroup HGL-Algorithm
+/// @brief Traversal policy specialization for backward searches on BF-directed hypergraphs.
 template <traits::c_bf_directed_hypergraph H>
 struct traversal_policy<H, traversal_direction::backward> {
+    /// @brief Retrieves the hyperedges entering the given vertex (backward star).
     static auto target_hyperedges(const H& h, typename H::id_type v_id) {
         return h.in_hyperedge_ids(v_id); // backward star
     }
 
+    /// @brief Retrieves the vertices originating the given hyperedge (tail nodes).
     static auto target_vertices(const H& h, typename H::id_type he_id) {
         return h.tail_ids(he_id);
     }

include/hgl/constants.hpp

@@ -15,31 +15,33 @@ namespace hgl {
 /// @ingroup HGL-Core
 /// @brief A constant representing the initial ID value of 0 for hypergraph elements.
 /// @see gl::initial_id_v
-using gl::initial_id_v;
+template <traits::c_id_type IdType>
+inline constexpr IdType initial_id_v = gl::initial_id_v<IdType>;
 
 /// @ingroup HGL-Core
 /// @brief A helper type that can be implicitly converted to the initial ID value of 0 for any valid ID type.
 /// @see gl::initial_id_t
-using gl::initial_id_t;
+using initial_id_t = gl::initial_id_t;
 
 /// @ingroup HGL-Core
 /// @brief An `initial_id_t` tag constant that can be used to represent the initial ID value of 0 for hypergraph elements in a type-safe manner.
 /// @see gl::initial_id
-using gl::initial_id;
+inline constexpr initial_id_t initial_id = gl::initial_id;
 
 /// @ingroup HGL-Core
 /// @brief A constant representing the invalid ID value for hypergraph elements, defined as the maximum value of the specified ID type.
 /// @see gl::invalid_id_v
-using gl::invalid_id_v;
+template <traits::c_id_type IdType>
+inline constexpr IdType invalid_id_v = gl::invalid_id_v<IdType>;
 
 /// @ingroup HGL-Core
 /// @brief A helper type that can be implicitly converted to the invalid ID value for any valid ID type.
 /// @see gl::invalid_id_t
-using gl::invalid_id_t;
+using invalid_id_t = gl::invalid_id_t;
 
 /// @ingroup HGL-Core
 /// @brief An `invalid_id_t` tag constant that can be used to represent the invalid ID value for hypergraph elements in a type-safe manner.
 /// @see gl::invalid_id
-using gl::invalid_id;
+inline constexpr invalid_id_t invalid_id = gl::invalid_id;
 
 } // namespace hgl