gl alg common docs + return_type -> result_type

Author: SpectraL519

include/gl/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 gl/algorithm/core.hpp
+/// @brief Core data structures and types used to control and track graph algorithm execution.
+
 #pragma once
 
 #include "gl/attributes/force_inline.hpp"
@@ -15,80 +18,179 @@ namespace gl::algorithm {
 
 // --- general types ---
 
+/// @ingroup GL GL-Algorithm
+/// @brief A tag type used to explicitly indicate the absence of a callback function.
+///
+/// > [!NOTE] Performance vs. Empty Lambdas
+/// >
+/// > Passing `empty_callback{}` is **not** the same as passing an empty lambda (e.g., `[]{}`).
+/// > Using this explicit tag type allows internal algorithms to use compile-time checks to
+/// > completely eliminate the callback invocation branch at compile time. This guarantees
+/// > strict zero-cost abstractions, vastly improves performance in unoptimized/debug builds,
+/// > and speeds up compilation times.
 struct empty_callback {};
 
+/// @ingroup GL GL-Algorithm GL-Types
+/// @brief Represents a generic tri-state decision for control flow.
+///
+/// Used by custom predicates to determine how to proceed with a given item, execution step, or operation.
+/// While heavily utilized in graph traversal algorithms, it is entirely decoupled from graph-specific
+/// logic and can be used in any generic context requiring explicit accept/reject/abort semantics.
 struct decision {
-    enum class eval : std::uint8_t { accept, reject, abort };
+    /// @brief The underlying evaluation states.
+    enum class eval : std::uint8_t {
+        accept, /// < Proceed with the current element or operation.
+        reject, /// < Skip the current element but continue the overall process.
+        abort /// < Immediately terminate the entire process or algorithm.
+    };
     using enum eval;
 
+    /// @brief Constructs a decision from an explicit evaluation state.
+    /// @param value The tri-state evaluation.
     constexpr decision(const eval value) : value(value) {}
 
+    /// @brief Constructs a decision from a boolean value.
+    /// @param value `true` maps to `accept`, `false` maps to `reject`.
     constexpr decision(const bool value) : value(value ? eval::accept : eval::reject) {}
 
+    /// @brief Assigns a boolean value to the decision.
+    /// @param value `true` maps to `accept`, `false` maps to `reject`.
+    /// @return A reference to this decision.
     constexpr decision& operator=(const bool value) {
         this->value = value ? eval::accept : eval::reject;
         return *this;
     }
 
+    /// @brief Evaluates the decision as a boolean.
+    /// @return `true` if the decision is `accept`, `false` otherwise.
     [[nodiscard]] constexpr operator bool() const {
         return this->value == eval::accept;
     }
 
+    /// @brief Compares the decision against a specific evaluation state.
+    /// @param value The state to compare against.
+    /// @return `true` if the states match.
     [[nodiscard]] constexpr bool operator==(const eval value) const {
         return this->value == value;
     }
 
+    /// @brief The stored evaluation state.
     eval value;
 };
 
-enum class result_discriminator : bool { ret = true, noret = false };
+/// @ingroup GL GL-Algorithm
+/// @brief Tag used to statically dictate whether an algorithm should return a constructed result or execute purely for side effects.
+///
+/// > [!NOTE] Namespace Availability
+/// >
+/// > Because this enum uses the `using enum` declaration, its members (`ret` and `noret`) are
+/// > injected directly into the `gl::algorithm` namespace. Hence, you can use `gl::algorithm::ret`
+/// > and `gl::algorithm::noret` directly without the `result_discriminator::` scope.
+///
+/// ### See Also
+/// - @ref gl::algorithm::result_type "result_type"
+/// - @ref gl::algorithm::non_void_result_type "non_void_result_type"
+enum class result_discriminator : bool {
+    ret = true, /// < The algorithm should build and return a result (e.g., a predecessor map).
+    noret = false /// < The algorithm will purely invoke callbacks and return void.
+};
 using enum result_discriminator;
 
-template <result_discriminator Result, typename ReturnType>
-using return_type = std::conditional_t<Result == algorithm::ret, ReturnType, void>;
-
-template <result_discriminator Result, typename ReturnType>
-using non_void_return_type =
-    std::conditional_t<Result == algorithm::ret, ReturnType, std::monostate>;
+/// @ingroup GL GL-Algorithm
+/// @brief Resolves to the specified `ResultType` if `Result` is `ret`, otherwise resolves to `void`.
+///
+/// ### See Also
+/// - @ref gl::algorithm::result_discriminator "result_discriminator"
+/// - @ref gl::algorithm::non_void_result_type "non_void_result_type"
+template <result_discriminator Result, typename ResultType>
+using result_type = std::conditional_t<Result == algorithm::ret, ResultType, void>;
+
+/// @ingroup GL GL-Algorithm
+/// @brief Resolves to the specified `ResultType` if `Result` is `ret`, otherwise resolves to `std::monostate`.
+///
+/// Useful for returning dummy values from conditionally compiled algorithm branches.
+///
+/// ### See Also
+/// - @ref gl::algorithm::result_discriminator "result_discriminator"
+/// - @ref gl::algorithm::result_type "result_type"
+template <result_discriminator Result, typename ResultType>
+using non_void_result_type =
+    std::conditional_t<Result == algorithm::ret, ResultType, std::monostate>;
 
 // --- traversal types ---
 
+/// @ingroup GL GL-Algorithm
+/// @brief Maps a vertex ID to its predecessor's ID in a traversal tree.
+/// @tparam GraphType The type of the graph being traversed.
 template <traits::c_graph GraphType>
 using predecessors_map = std::vector<typename GraphType::id_type>;
 
+/// @ingroup GL GL-Algorithm
+/// @brief Represents an active node in a search frontier (e.g., a BFS queue or DFS stack).
+/// @tparam GraphType The type of the graph being searched.
 template <traits::c_graph GraphType>
 struct search_node {
     using id_type = typename GraphType::id_type;
 
+    /// @brief Constructs a search node acting as a root (predecessor is itself).
+    /// @param vertex_id The ID of the vertex.
     search_node(id_type vertex_id) : vertex_id(vertex_id), pred_id(vertex_id) {}
 
+    /// @brief Constructs a search node with an explicit predecessor.
+    /// @param vertex_id The ID of the vertex.
+    /// @param pred_id The ID of the vertex's predecessor.
     search_node(id_type vertex_id, id_type pred_id) : vertex_id(vertex_id), pred_id(pred_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 vertex currently being searched.
     id_type vertex_id;
+    /// @brief The ID of the predecessor from which this vertex was reached.
     id_type pred_id;
 };
 
 // --- constants ---
 
+/// @ingroup GL GL-Algorithm
+/// @brief Constant representing the absence of a root vertex ID for a specific ID type.
+///
+/// ### See Also
+/// - @ref gl::invalid_id_v "gl::invalid_id_v"
+/// - @ref gl::algorithm::no_root_t "no_root_t"
+/// - @ref gl::algorithm::no_root "no_root"
 template <traits::c_id_type IdType>
 inline constexpr IdType no_root_v = invalid_id_v<IdType>;
 
+/// @ingroup GL GL-Algorithm
+/// @brief Tag type providing an implicit conversion to the appropriate `no_root_v` for any numeric ID type.
+///
+/// ### See Also
+/// - @ref gl::algorithm::no_root_v "no_root_v"
+/// - @ref gl::algorithm::no_root "no_root"
 struct no_root_t {
+    /// @brief Implicitly converts to the numeric `no_root_v` constant.
     template <traits::c_id_type IdType>
     [[nodiscard]] constexpr operator IdType() const noexcept {
         return no_root_v<IdType>;
     }
 
+    /// @brief Checks if a given ID matches the `no_root_v` constant.
     template <traits::c_id_type IdType>
     [[nodiscard]] friend constexpr bool operator==(const IdType& lhs, no_root_t) noexcept {
         return lhs == no_root_v<IdType>;
     }
 };
 
+/// @ingroup GL GL-Algorithm
+/// @brief Global constant representing the absence of a root vertex.
+///
+/// ### See Also
+/// - @ref gl::algorithm::no_root_v "no_root_v"
+/// - @ref gl::algorithm::no_root_t "no_root_t"
 inline constexpr no_root_t no_root{};
 
 } // namespace gl::algorithm

include/gl/algorithm/traits.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/algorithm/traits.hpp
+/// @brief C++20 concepts for validating custom callbacks and predicates passed to graph algorithms.
+
 #pragma once
 
 #include "gl/algorithm/core.hpp"
@@ -10,24 +13,41 @@
 
 namespace gl::traits {
 
+/// @ingroup GL GL-Traits
+/// @brief Concept checking if a given type is the @ref gl::algorithm::empty_callback "empty_callback" tag.
 template <typename F>
 concept c_empty_callback = std::same_as<F, algorithm::empty_callback>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept checking if a type is callable with specific arguments and returns a specific type.
+/// @tparam F The callable type.
+/// @tparam ReturnType The expected return type.
+/// @tparam Args The parameter types the callable must accept.
 template <typename F, typename ReturnType, typename... Args>
 concept c_callback = std::is_invocable_r_v<ReturnType, F, Args...>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept allowing either a valid callback or the explicit absence of one through the use of @ref gl::algorithm::empty_callback "empty_callback".
 template <typename F, typename ReturnType, typename... Args>
 concept c_optional_callback = c_empty_callback<F> or c_callback<F, ReturnType, Args...>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept checking if a type is a boolean predicate callable with specific arguments.
 template <typename F, typename... Args>
 concept c_predicate = std::predicate<F, Args...>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept allowing either a valid boolean predicate or the explicit absence of one through the use of @ref gl::algorithm::empty_callback "empty_callback".
 template <typename F, typename... Args>
 concept c_optional_predicate = c_empty_callback<F> or c_predicate<F, Args...>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept checking if a type is a predicate returning a @ref gl::algorithm::decision "decision".
 template <typename F, typename... Args>
 concept c_decision_predicate = std::is_invocable_r_v<algorithm::decision, F, Args...>;
 
+/// @ingroup GL GL-Traits
+/// @brief Concept allowing either a valid decision predicate or the explicit absence of one.
 template <typename F, typename... Args>
 concept c_optional_decision_predicate = c_empty_callback<F> or c_decision_predicate<F, Args...>;
 

include/gl/algorithm/traversal/breadth_first_search.hpp

@@ -16,7 +16,7 @@ template <
     traits::c_graph G,
     traits::c_optional_callback<void, typename G::id_type> PreVisitCallback = empty_callback,
     traits::c_optional_callback<void, typename G::id_type> PostVisitCallback = empty_callback>
-return_type<Result, predecessors_map<G>> breadth_first_search(
+result_type<Result, predecessors_map<G>> breadth_first_search(
     const G& graph,
     const typename G::id_type root_vertex_id = no_root,
     PreVisitCallback pre_visit = {},

include/gl/algorithm/traversal/depth_first_search.hpp

@@ -16,7 +16,7 @@ template <
     traits::c_graph G,
     traits::c_optional_callback<void, typename G::id_type> PreVisitCallback = empty_callback,
     traits::c_optional_callback<void, typename G::id_type> PostVisitCallback = empty_callback>
-return_type<Result, predecessors_map<G>> depth_first_search(
+result_type<Result, predecessors_map<G>> depth_first_search(
     const G& graph,
     const typename G::id_type root_vertex_id = no_root,
     PreVisitCallback pre_visit = {},
@@ -64,7 +64,7 @@ template <
     traits::c_graph G,
     traits::c_optional_callback<void, typename G::id_type> PreVisitCallback = empty_callback,
     traits::c_optional_callback<void, typename G::id_type> PostVisitCallback = empty_callback>
-return_type<Result, predecessors_map<G>> recursive_depth_first_search(
+result_type<Result, predecessors_map<G>> recursive_depth_first_search(
     const G& graph,
     const typename G::id_type root_vertex_id = no_root,
     PreVisitCallback pre_visit = {},

include/gl/algorithm/util.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/algorithm/util.hpp
+/// @brief Internal utilities and default behaviors used by the graph traversal algorithms.
+
 #pragma once
 
 #include "gl/algorithm/core.hpp"
@@ -11,37 +14,66 @@
 
 namespace gl::algorithm {
 
+/// @ingroup GL GL-Algorithm
+/// @brief Initializes a predecessor map based on the static result discriminator.
+/// @tparam Result The compilation tag determining if the map should actually be built.
+/// @tparam G The type of the graph.
+/// @param graph The graph instance to size the map against.
+/// @return A fully sized and initialized `predecessors_map` if `Result == ret`, otherwise a dummy `std::monostate`.
 template <result_discriminator Result, traits::c_graph G>
-[[nodiscard]] gl_attr_force_inline non_void_return_type<Result, predecessors_map<G>>
+[[nodiscard]] gl_attr_force_inline non_void_result_type<Result, predecessors_map<G>>
 init_predecessors_map(const G& graph) {
-    using return_t = non_void_return_type<Result, predecessors_map<G>>;
+    using return_t = non_void_result_type<Result, predecessors_map<G>>;
     if constexpr (Result == ret)
         return return_t(graph.n_vertices(), invalid_id);
     else
         return return_t();
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Checks if a specific vertex was reached during a traversal.
+/// @tparam IdType The integral type of the vertex ID.
+/// @param pred_map The predecessor map populated by the traversal.
+/// @param vertex_id The vertex ID to query.
+/// @return `true` if the vertex has a valid assigned predecessor, `false` otherwise.
 template <traits::c_id_type IdType>
 [[nodiscard]] gl_attr_force_inline bool is_reachable(
     const traits::c_random_access_range_of<IdType> auto& pred_map, IdType vertex_id
 ) noexcept {
     return pred_map[to_idx(vertex_id)] != invalid_id;
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Initializes a search frontier (queue or stack) with the starting root vertex.
+/// @tparam G The type of the graph.
+/// @tparam InitRangeType The underlying container type for the frontier.
+/// @param root_vertex_id The ID of the starting vertex.
+/// @return A container initialized with a single @ref search_node for the root vertex.
 template <
     traits::c_graph G,
     traits::c_forward_range_of<search_node<G>> InitRangeType = std::vector<search_node<G>>>
 [[nodiscard]] gl_attr_force_inline InitRangeType init_range(typename G::id_type root_vertex_id) {
     return InitRangeType{search_node<G>{root_vertex_id}};
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Generates a default lambda predicate that checks if a vertex has not yet been visited.
+/// @param visited A reference to the boolean array tracking visited vertices.
+/// @return A callable predicate evaluating to `true` if the vertex is unvisited.
 [[nodiscard]] gl_attr_force_inline auto default_visit_vertex_predicate(std::vector<bool>& visited) {
     return [&](traits::c_id_type auto vertex_id) -> bool { return not visited[to_idx(vertex_id)]; };
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Generates a default lambda callback that marks a vertex as visited and updates the predecessor map.
+/// @tparam G The type of the graph.
+/// @tparam Result The static discriminator indicating if the predecessor map should be updated.
+/// @param visited A reference to the boolean array tracking visited vertices.
+/// @param pred_map A reference to the active predecessor map.
+/// @return A callable callback that executes state updates upon visiting a vertex.
 template <traits::c_graph G, result_discriminator Result>
 [[nodiscard]] gl_attr_force_inline auto default_visit_callback(
-    std::vector<bool>& visited, non_void_return_type<Result, predecessors_map<G>>& pred_map
+    std::vector<bool>& visited, non_void_result_type<Result, predecessors_map<G>>& pred_map
 ) {
     using id_type = typename G::id_type;
     return [&](id_type vertex_id, id_type pred_id) {
@@ -53,6 +85,12 @@ template <traits::c_graph G, result_discriminator Result>
     };
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Generates a default lambda predicate that checks if an adjacent vertex should be enqueued into the search frontier.
+/// @tparam G The type of the graph.
+/// @tparam AsResult If `true`, the generated predicate returns a @ref decision instead of a raw boolean.
+/// @param visited A reference to the boolean array tracking visited vertices.
+/// @return A callable predicate that returns `true` (or `decision::accept`) if the adjacent vertex has not been visited.
 template <traits::c_graph G, bool AsResult = false>
 [[nodiscard]] gl_attr_force_inline auto default_enqueue_vertex_predicate(std::vector<bool>& visited
 ) {

include/hgl/algorithm/core.hpp

@@ -27,8 +27,8 @@ using gl::algorithm::decision;
 using gl::algorithm::result_discriminator;
 using enum result_discriminator;
 
-using gl::algorithm::non_void_return_type;
-using gl::algorithm::return_type;
+using gl::algorithm::non_void_result_type;
+using gl::algorithm::result_type;
 
 using gl::algorithm::no_root;
 using gl::algorithm::no_root_t;

include/hgl/algorithm/traversal/backward_search.hpp

@@ -18,7 +18,7 @@ template <
     traits::c_forward_range_of<typename H::id_type> RootRange = std::vector<typename H::id_type>,
     traits::c_optional_callback<void, const search_node<H>&> PreVisitCallback = empty_callback,
     traits::c_optional_callback<void, const search_node<H>&> PostVisitCallback = empty_callback>
-return_type<Result, search_tree<H>> backward_bfs(
+result_type<Result, search_tree<H>> backward_bfs(
     const H& hypergraph,
     const RootRange& root_vertices,
     const PreVisitCallback& pre_visit = {},
@@ -59,7 +59,7 @@ template <
     traits::c_forward_range_of<typename H::id_type> RootRange = std::vector<typename H::id_type>,
     traits::c_optional_callback<void, const search_node<H>&> PreVisitCallback = empty_callback,
     traits::c_optional_callback<void, const search_node<H>&> PostVisitCallback = empty_callback>
-return_type<Result, search_tree<H>> backward_dfs(
+result_type<Result, search_tree<H>> backward_dfs(
     const H& hypergraph,
     const RootRange& root_vertices,
     const PreVisitCallback& pre_visit = {},