concrete bfs docs + @see fix

Author: SpectraL519

include/gl/algorithm/spanning_tree/prim_mst.hpp

@@ -73,7 +73,8 @@ struct mst_descriptor {
 /// @param graph The undirected graph to evaluate.
 /// @param root_id The starting vertex ID for the MST calculation. Defaults to the graph's `initial_id` if `invalid_id` is passed.
 /// @return A @ref gl::algorithm::mst_descriptor "mst_descriptor" containing the accumulated minimum weight and the sequence of edges forming the tree.
-/// @see @ref gl::algorithm::vertex_heap_prim_mst "vertex_heap_prim_mst" For the vertex-heap variant of the Prim's MST finding algorithm.
+/// ### See Also
+/// - @ref gl::algorithm::vertex_heap_prim_mst "vertex_heap_prim_mst" For the vertex-heap variant of the Prim's MST finding algorithm.
 /// @hideparams
 template <traits::c_undirected_graph G>
 [[nodiscard]] mst_descriptor<G> edge_heap_prim_mst(const G& graph, typename G::id_type root_id) {
@@ -164,7 +165,8 @@ template <traits::c_undirected_graph G>
 /// @param graph The undirected graph to evaluate.
 /// @param root_id The starting vertex ID for the MST calculation. Defaults to the graph's `initial_id` if `invalid_id` is passed.
 /// @return A @ref gl::algorithm::mst_descriptor "mst_descriptor" containing the accumulated minimum weight and the sequence of edges forming the tree.
-/// @see @ref gl::algorithm::edge_heap_prim_mst "edge_heap_prim_mst" For the vertex-heap variant of the Prim's MST finding algorithm.
+/// ### See Also
+/// - @ref gl::algorithm::edge_heap_prim_mst "edge_heap_prim_mst" For the vertex-heap variant of the Prim's MST finding algorithm.
 /// @hideparams
 template <traits::c_undirected_graph G>
 requires(traits::c_has_numeric_limits_max<vertex_distance_type<G>>)

include/gl/algorithm/topology/coloring.hpp

@@ -117,7 +117,8 @@ template <
 /// @brief Convenience wrapper for the @ref gl::algorithm::bipartite_coloring "bipartite_coloring" algorithm to check if a graph is bipartite without extracting the exact coloring map.
 /// @param graph The graph to evaluate.
 /// @return `true` if the graph is bipartite (2-colorable), `false` otherwise.
-/// @see @ref gl::algorithm::apply_coloring "apply_coloring"
+/// ### See Also
+/// - @ref gl::algorithm::apply_coloring "apply_coloring"
 [[nodiscard]] gl_attr_force_inline bool is_bipartite(const traits::c_graph auto& graph) {
     return bipartite_coloring(graph).has_value();
 }

include/gl/algorithm/traversal/breadth_first_search.hpp

@@ -26,7 +26,8 @@ namespace gl::algorithm {
 ///
 /// ### Example Usage
 /// ```cpp
-/// auto pred_map = gl::algorithm::breadth_first_search(graph, start_id); // (1)!
+/// auto pred_map
+///     = gl::algorithm::breadth_first_search(graph, start_id); // (1)!
 ///
 /// gl::algorithm::breadth_first_search<gl::algorithm::noret>( // (2)!
 ///     graph,
@@ -55,7 +56,7 @@ namespace gl::algorithm {
 /// ### Template Parameters
 /// | Parameter | Description | Constraint |
 /// | :-------- | :--- | :--- |
-/// | Result | @ref gl::algorithm::result_discriminator "Discriminator" dictating if the algorithm should return a predecessor map (`ret`) or `void` (`noret`). | Must be a valid @ref gl::algorithm::result_discriminator "result_discriminator" enum value. |
+/// | Result | Discriminator dictating if the algorithm should return a predecessor map (`ret`) or `void` (`noret`). | Must be a valid @ref gl::algorithm::result_discriminator "result_discriminator" enum value. |
 /// | G | The type of the graph being traversed. | Must satisfy the [**c_graph**](gl_concepts.md#gl-traits-c-graph) concept. |
 /// | PreVisitCallback | Type of the callable executed immediately before a vertex is officially visited. | Must be one of:<br/>- `(id_type) -> void` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |
 /// | PostVisitCallback | Type of the callable executed after all adjacent edges of a vertex are evaluated. | Must be one of:<br/>- `(id_type) -> void` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |

include/gl/algorithm/traversal/depth_first_search.hpp

@@ -34,7 +34,8 @@ namespace gl::algorithm {
 ///
 /// ### Example Usage
 /// ```cpp
-/// auto pred_map = gl::algorithm::depth_first_search(graph, start_id); // (1)!
+/// auto pred_map
+///     = gl::algorithm::depth_first_search(graph, start_id); // (1)!
 ///
 /// gl::algorithm::depth_first_search<gl::algorithm::noret>( // (2)!
 ///     graph,
@@ -135,7 +136,6 @@ result_type<Result, predecessors_map<G>> depth_first_search(
 ///
 /// ### Example Usage
 /// ```cpp
-/// // Execution purely for side-effects from a specific root
 /// gl::algorithm::recursive_depth_first_search<gl::algorithm::noret>( // (1)!
 ///     graph,
 ///     start_id, // (2)!
@@ -144,7 +144,7 @@ result_type<Result, predecessors_map<G>> depth_first_search(
 /// );
 /// ```
 ///
-/// 1\. Execution purely for side-effects over the entire graph. Uses the @ref gl::algorithm::result_discriminator "noret" discriminator to completely compile away the predecessor map allocations.
+/// 1\. Execution purely for side-effects. Uses the @ref gl::algorithm::result_discriminator "noret" discriminator to completely compile away the predecessor map allocations.
 ///
 /// 2\. Initiates the recursion from `start_id`.
 ///

include/gl/impl/impl_tags.hpp

@@ -28,7 +28,8 @@ struct list_t {
 /// @ingroup GL GL-Core
 /// @headerfile gl/impl/impl_tags.hpp
 /// @brief Tag struct for the flattened adjacency list graph implementation.
-/// @see @ref gl::flat_jagged_vector "flat_jagged_vector" : For the data structure used for the underlying model implementation.
+/// ### See Also
+/// - @ref gl::flat_jagged_vector "flat_jagged_vector" : For the data structure used for the underlying model 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.
@@ -53,7 +54,8 @@ struct matrix_t {
 /// @ingroup GL GL-Core
 /// @headerfile gl/impl/impl_tags.hpp
 /// @brief Tag struct for the flattened adjacency matrix graph implementation.
-/// @see @ref gl::flat_matrix "flat_matrix" : For the data structure used for the underlying model implementation.
+/// ### See Also
+/// - @ref gl::flat_matrix "flat_matrix" : For the data structure used for the underlying model 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.

include/gl/io/ranges.hpp

@@ -104,7 +104,8 @@ range_formatter(R&& r, std::string_view, std::string_view, std::string_view)
 /// @param range The range object to format.
 /// @param sep The separator string between elements. Defaults to `", "`.
 /// @return A @ref range_formatter configured for set-style output.
-/// @see @ref gl::io::multiline_set_formatter "multiline_set_formatter"
+/// ### See Also
+/// - @ref gl::io::multiline_set_formatter "multiline_set_formatter"
 template <std::ranges::range R>
 auto set_formatter(R&& range, std::string_view sep = ", ") {
     using view_type = std::views::all_t<R>;
@@ -136,7 +137,8 @@ auto set_formatter(R&& range, std::string_view sep = ", ") {
 /// @tparam R The type of the range.
 /// @param range The range object to format.
 /// @return A @ref range_formatter configured for multiline set-style output.
-/// @see @ref gl::io::set_formatter "set_formatter"
+/// ### See Also
+/// - @ref gl::io::set_formatter "set_formatter"
 template <std::ranges::range R>
 auto multiline_set_formatter(R&& range) {
     using view_type = std::views::all_t<R>;

include/hgl/algorithm/core.hpp

@@ -25,35 +25,40 @@ namespace algorithm {
 
 /// @ingroup HGL-Algorithm
 /// @copybrief gl::algorithm::empty_callback
-/// @see gl::algorithm::empty_callback for a more detailed description.
+/// ### See Also
+/// - @ref gl::algorithm::empty_callback : For a more detailed description.
 using empty_callback = gl::algorithm::empty_callback;
 
 /// @ingroup HGL-Algorithm
 /// @copybrief gl::algorithm::decision
-/// @see gl::algorithm::decision for the full type definition
+/// ### See Also
+/// - @ref gl::algorithm::decision : For the full type definition.
 using decision = gl::algorithm::decision;
 
 /// @ingroup HGL-Algorithm
 /// @copybrief gl::algorithm::result_discriminator
-/// @see gl::algorithm::result_discriminator for the full type definition.
+/// ### See Also
+/// - @ref gl::algorithm::result_discriminator : For the full type definition.
 using result_discriminator = gl::algorithm::result_discriminator;
 using enum result_discriminator;
 
 /// @ingroup HGL-Algorithm
 /// @copybrief gl::algorithm::result_type
-/// @see gl::algorithm::result_type for the full type definition.
+/// ### See Also
+/// - @ref 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.
+/// @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
+/// ### See Also
+/// - @ref gl::algorithm::no_root_v
 template <traits::c_id_type IdType>
 inline constexpr IdType no_root_v = gl::algorithm::no_root_v<IdType>;
 
@@ -64,7 +69,8 @@ using no_root_t = gl::algorithm::no_root_t;
 
 /// @ingroup HGL-Algorithm
 /// @copybrief gl::algorithm::no_root
-/// @see gl::algorithm::no_root
+/// ### See Also
+/// - @ref gl::algorithm::no_root
 inline constexpr no_root_t no_root = gl::algorithm::no_root;
 
 // --- traversal types ---
@@ -111,7 +117,7 @@ struct search_node {
 ///
 /// 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.
+/// connecting hyperedge, enabling \f$O(1)\f$ lookups and and \f$O(\vert V \vert)\f$ path reconstruction.
 ///
 /// @tparam H The type of the hypergraph being searched.
 template <traits::c_hypergraph H>

include/hgl/algorithm/traversal/breadth_first_search.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/traversal/breadth_first_search.hpp
+/// @brief Concrete Breadth-First Search (BFS) traversal algorithm implementation for hypergraphs.
+
 #pragma once
 
 #include "hgl/algorithm/core.hpp"
@@ -10,6 +13,48 @@
 
 namespace hgl::algorithm {
 
+/// @ingroup HGL-Algorithm
+/// @brief Executes a concrete Breadth-First Search (BFS) traversal over the hypergraph.
+///
+/// This function utilizes the generic @ref hgl::algorithm::bfs "bfs" template to perform a standard queue-based traversal.
+/// It automatically manages the visited states (for both vertices and hyperedges), search tree tracking, and queue initialization.
+///
+/// If a specific `root_vertex_id` is provided, the algorithm explores only the connected component reachable from that root.
+/// If `no_root` is used, it iteratively ensures that every disconnected component in the entire hypergraph is fully traversed.
+///
+/// ### Example Usage
+/// ```cpp
+/// auto search_tree
+///     = hgl::algorithm::breadth_first_search(hypergraph, start_id); // (1)!
+///
+/// hgl::algorithm::breadth_first_search<hgl::algorithm::noret>( // (2)!
+///     hypergraph,
+///     hgl::algorithm::no_root, // (3)!
+///     [](const auto& node) { std::cout << "Pre-visit: " << node.vertex_id << '\n'; },
+///     [](const auto& node) { std::cout << "Post-visit: " << node.vertex_id << '\n'; }
+/// );
+/// ```
+///
+/// 1\. Executes a standard BFS returning a search tree mapped to the components reachable from `start_id`.
+///
+/// 2\. Executes a BFS purely for side-effects (callbacks) without allocating memory for a search tree.
+///
+/// 3\. Passing `no_root` forces the algorithm to iterate over all vertices, ensuring disjoint components are traversed.
+///
+/// ### Template Parameters
+/// | Parameter | Description | Constraint |
+/// | :-------- | :--- | :--- |
+/// | Result | Controls whether the algorithm builds and returns a search tree (`ret`) or evaluates purely for side effects (`noret`). | Must be a valid @ref hgl::algorithm::result_discriminator "result_discriminator" enum value. |
+/// | H | The type of the hypergraph being searched. | Must satisfy the [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph) concept. |
+/// | PreVisitCallback | Type of the callable executed immediately before officially visiting a vertex. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+/// | PostVisitCallback | Type of the callable executed after all adjacent elements are evaluated. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+///
+/// @param hypergraph The hypergraph to traverse.
+/// @param root_vertex_id The ID of the vertex to start the search from. If `no_root`, searches the entire hypergraph.
+/// @param pre_visit Hook executed immediately before officially visiting the vertex.
+/// @param post_visit Hook executed after all adjacent hyperedges and target vertices of the current node have been evaluated.
+/// @return A @ref hgl::algorithm::search_tree "search_tree" if `Result == ret`, otherwise nothing (`void`).
+/// @hideparams
 template <
     result_discriminator Result = ret,
     traits::c_hypergraph H,

include/hgl/impl/impl_tags.hpp

@@ -58,7 +58,8 @@ struct list_t {
 ///
 /// @tparam LayoutTag Specifies the memory layout orientation for the underlying data structure.
 /// @tparam IdType The underlying integer type used for identifiers.
-/// @see @ref gl::flat_jagged_vector "flat_jagged_vector" for the data structure used for the underlying model implementation.
+/// ### See Also
+/// - @ref gl::flat_jagged_vector "flat_jagged_vector" for the data structure used for the underlying model implementation.
 template <traits::c_hypergraph_layout_tag LayoutTag, traits::c_id_type IdType>
 struct flat_list_t {
     /// @brief Self type alias.
@@ -115,7 +116,8 @@ struct matrix_t {
 ///
 /// @tparam LayoutTag Specifies the memory layout orientation for the underlying data structure (must be asymmetric).
 /// @tparam IdType The underlying integer type used for identifiers.
-/// @see @ref gl::flat_matrix "flat_matrix" for the data structure used for the underlying model implementation.
+/// ### See Also
+/// - @ref gl::flat_matrix "flat_matrix" for the data structure used for the underlying model implementation.
 template <traits::c_hypergraph_asymmetric_layout_tag LayoutTag, traits::c_id_type IdType>
 struct flat_matrix_t {
     /// @brief Self type alias.

include/hgl/types.hpp

@@ -43,19 +43,22 @@ using gl::to_diff;
 
 /// @ingroup HGL-Types
 /// @brief @copybrief gl::flat_jagged_vector
-/// @see gl::flat_jagged_vector for the full type definition
+/// ### See Also
+/// - @ref gl::flat_jagged_vector : For the full type definition.
 template <std::semiregular T>
 using flat_jagged_vector = gl::flat_jagged_vector<T>;
 
 /// @ingroup HGL-Types
 /// @brief @copybrief gl::flat_matrix
-/// @see gl::flat_matrix for the full type definition
+/// ### See Also
+/// - @ref gl::flat_matrix "gl::flat_matrix" : For the full type definition.
 template <std::semiregular T>
 using flat_matrix = gl::flat_matrix<T>;
 
 /// @ingroup HGL-Types
 /// @brief @copybrief gl::homogeneous_pair
-/// @see gl::homogeneous_pair for the full type definition
+/// ### See Also
+/// - @ref gl::homogeneous_pair : For the full type definition.
 template <typename T>
 using homogeneous_pair = gl::homogeneous_pair<T>;
 
@@ -69,7 +72,8 @@ using homogeneous_pair = gl::homogeneous_pair<T>;
 /// > This type is used as a default `properties_type` for hypergraph components that do not require any user-defined data.
 /// > It serves as a marker to indicate that the component is *property-less* and can be optimized accordingly.
 ///
-/// @see gl::empty_properties for the full type definition
+/// ### See Also
+/// - @ref gl::empty_properties : For the full type definition.
 using empty_properties = gl::empty_properties;
 
 /// @ingroup HGL-Core
@@ -79,22 +83,26 @@ using empty_properties = gl::empty_properties;
 /// >
 /// > This type is used internally by the library to optimize storage for hypergraph components that have no properties.
 ///
-/// @see gl::empty_properties_map for the full type definition
+/// ### See Also
+/// - @ref gl::empty_properties_map : For the full type definition.
 using empty_properties_map = gl::empty_properties_map;
 
 /// @ingroup HGL-Core
 /// @brief @copybrief gl::name_property
-/// @see gl::name_property for the full type definition
+/// ### See Also
+/// - @ref gl::name_property : For the full type definition.
 using name_property = gl::name_property;
 
 /// @ingroup HGL-Core
 /// @brief @copybrief gl::dynamic_properties
-/// @see gl::dynamic_properties for the full type definition
+/// ### See Also
+/// - @ref gl::dynamic_properties : For the full type definition.
 using dynamic_properties = gl::dynamic_properties;
 
 /// @ingroup HGL-Core
 /// @brief A property struct providing arithmetic weight for hyperedges or vertices.
-/// @see gl::weight_property for the full type definition
+/// ### See Also
+/// - @ref gl::weight_property : For the full type definition.
 template <traits::c_arithmetic WeightType = double>
 using weight_property = gl::weight_property<WeightType>;