gl alg topology docs

Author: SpectraL519

include/gl/algorithm/topology/coloring.hpp

@@ -2,15 +2,65 @@
 // 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/topology/coloring.hpp
+/// @brief Algorithms for detecting and computing graph colorings.
+
 #pragma once
 
 #include "gl/algorithm/core.hpp"
 #include "gl/algorithm/templates/bfs.hpp"
 
 namespace gl::algorithm {
 
+/// @ingroup GL GL-Algorithm
+/// @brief Alias for a container mapping vertex indices to their calculated binary (bipartite) colors.
 using bicoloring_type = std::vector<binary_color>;
 
+/// @ingroup GL GL-Algorithm
+/// @brief Attempts to compute a valid bipartite (2-color) coloring for the given graph.
+///
+/// This algorithm utilizes the generic @ref gl::algorithm::bfs "bfs" template to traverse the graph and
+/// alternate colors between adjacent vertices. If an edge connects two vertices of the same color
+/// (indicating an odd-length cycle), the graph is not bipartite, and the search immediately aborts.
+///
+/// ### Example Usage
+/// ```cpp
+/// if (auto coloring = gl::algorithm::bipartite_coloring(graph)) // (1)!
+///     gl::algorithm::apply_coloring(graph, *coloring); // (2)!
+/// else
+///     std::cout << "Graph contains an odd cycle and is not bipartite.\n";
+/// ```
+///
+/// 1\. Attempts to find a valid 2-coloring for the graph. Returns `std::nullopt` if impossible.
+///
+/// 2\. If successful, directly modifies the graph's internal vertex properties to store the colors.
+///     **NOTE:** This operation is only available if the property type of the graph's vertices satisfies [**c_binary_color_properties_type**](gl_concepts.md#gl-traits-c-binary-color-properties-type).
+///
+/// > [!INFO] Algorithmic Complexity
+/// >
+/// > The time complexity depends entirely on the underlying representation of `GraphType`:
+/// >
+/// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$
+/// >   - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t".
+/// >
+/// > - **Dense Adjacency Matrix Representations**: \f$O(|V|^2)\f$
+/// >   - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t".
+/// >   - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row.
+///
+/// ### Template Parameters
+/// | Parameter | Description |
+/// | :-------- | :--- |
+/// | G | The type of the graph being traversed. |
+/// | PreVisitCallback | Type of the callable executed immediately before a vertex is officially visited. |
+/// | PostVisitCallback | Type of the callable executed after all adjacent edges of a vertex are evaluated. |
+///
+/// @param graph The graph to evaluate.
+/// @param pre_visit Hook executed immediately before the internal visit logic.
+/// @param post_visit Hook executed after all adjacent edges of the current vertex have been enqueued.
+/// @return An `std::optional` containing the @ref gl::algorithm::bicoloring_type "bicoloring_type" map if the graph is bipartite. Returns `std::nullopt` otherwise.
+/// ### See Also
+/// - @ref gl::algorithm::is_bipartite "is_bipartite"
+/// - @ref gl::algorithm::apply_coloring "apply_coloring"
 template <
     traits::c_graph G,
     traits::c_optional_callback<void, typename G::id_type> PreVisitCallback = empty_callback,
@@ -64,10 +114,30 @@ template <
     return coloring;
 }
 
+/// @ingroup GL GL-Algorithm
+/// @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"
 [[nodiscard]] gl_attr_force_inline bool is_bipartite(const traits::c_graph auto& graph) {
     return bipartite_coloring(graph).has_value();
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Applies a computed range of binary colors to the property payload of each vertex in the graph.
+///
+/// ### Template Parameters
+/// | Parameter | Description |
+/// | :-------- | :--- |
+/// | `G` | The type of the graph to modify. Must have compatible color properties. |
+/// | `ColorRange` | The type of the range containing the computed colors. |
+///
+/// @param graph The mutable graph instance whose properties will be updated.
+/// @param color_range A sized range (e.g., @ref gl::algorithm::bicoloring_type "bicoloring_type") matching the vertex count.
+/// @return `true` if the coloring was successfully applied, `false` if the size of the range does not match the graph's vertex count.
+/// ### See Also
+/// - @ref gl::algorithm::bipartite_coloring "bipartite_coloring"
+/// - @ref gl::algorithm::is_bipartite "is_bipartite"
 template <traits::c_graph G, traits::c_sized_range_of<binary_color> ColorRange>
 requires(traits::c_binary_color_properties_type<typename G::vertex_properties_type>)
 bool apply_coloring(G& graph, const ColorRange& color_range) {

include/gl/algorithm/topology/topological_sort.hpp

@@ -2,13 +2,64 @@
 // 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/topology/topological_sort.hpp
+/// @brief Algorithms for computing the topological ordering of directed acyclic graphs.
+
 #pragma once
 
 #include "gl/algorithm/core.hpp"
 #include "gl/algorithm/templates/bfs.hpp"
 
 namespace gl::algorithm {
 
+/// @ingroup GL GL-Algorithm
+/// @brief Computes a topological ordering of the vertices in a Directed Acyclic Graph (DAG).
+///
+/// This implementation relies on Kahn's Algorithm. It utilizes the generic @ref gl::algorithm::bfs "bfs"
+/// template, seeding the queue with all vertices that have an in-degree of 0. As vertices are processed,
+/// the in-degrees of adjacent vertices are iteratively decremented.
+///
+/// If the final sorted order does not contain all vertices in the graph, it indicates the presence
+/// of a cycle, meaning the graph is not a DAG.
+///
+/// ### Example Usage
+/// ```cpp
+/// if (auto top_order = gl::algorithm::topological_sort(graph)) { // (1)!
+///     std::cout << "Topological Order: "
+///               << gl::io::range_formatter(top_order.value()) // (2)!
+///               << '\n';
+/// }
+/// else {
+///     std::cout << "Graph contains a cycle!\n";
+/// }
+/// ```
+///
+/// 1\. Attempts to compute the ordering. Fails and returns `std::nullopt` if a cycle is detected.
+///
+/// 2\. Prints the topologically sorted vector of vertex IDs using the @ref gl::io::range_formatter "range_formatter" helper.
+///
+/// > [!INFO] Algorithmic Complexity
+/// >
+/// > The time complexity depends entirely on the underlying representation of `GraphType`:
+/// >
+/// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$
+/// >   - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t".
+/// >
+/// > - **Dense Adjacency Matrix Representations**: \f$O(|V|^2)\f$
+/// >   - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t".
+/// >   - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row.
+///
+/// ### Template Parameters
+/// | Parameter | Description |
+/// | :-------- | :--- |
+/// | `G` | The type of the directed graph being traversed. Must satisfy [**c_directed_graph**](gl_concepts.md#gl-traits-c-directed-graph) |
+/// | `PreVisitCallback` | Type of the callable executed immediately before a vertex is pushed into the sort order. |
+/// | `PostVisitCallback` | Type of the callable executed after all adjacent edges of a vertex are evaluated. |
+///
+/// @param graph The directed graph to evaluate.
+/// @param pre_visit Hook executed immediately before the internal sort logic processes a vertex.
+/// @param post_visit Hook executed after all adjacent edges of the current vertex have been evaluated and their in-degrees decremented.
+/// @return An `std::optional` containing a vector of vertex IDs in topological order or `std::nullopt` if the graph is not a DAG.
 template <
     traits::c_directed_graph G,
     traits::c_optional_callback<void, typename G::id_type> PreVisitCallback = empty_callback,

include/gl/algorithm/traversal/breadth_first_search.hpp

@@ -17,7 +17,7 @@ namespace gl::algorithm {
 /// @ingroup GL GL-Algorithm
 /// @brief Executes a concrete Breadth-First Search (BFS) traversal over the graph.
 ///
-/// This function utilizes the generic @ref gl::algorithm::bfs "bfs" engine to perform a standard queue-based traversal.
+/// This function utilizes the generic @ref gl::algorithm::bfs "bfs" template to perform a standard queue-based traversal.
 /// It automatically manages the visited states, predecessor tracking, and queue initialization.
 ///
 /// If a specific `root_vertex_id` is provided, the algorithm explores only the connected component

include/gl/algorithm/traversal/depth_first_search.hpp

@@ -17,7 +17,7 @@ namespace gl::algorithm {
 /// @ingroup GL GL-Algorithm
 /// @brief Executes a concrete iterative Depth-First Search (DFS) traversal over the graph.
 ///
-/// This function utilizes the generic @ref gl::algorithm::dfs "dfs" engine to perform a standard, stack-based traversal.
+/// This function utilizes the generic @ref gl::algorithm::dfs "dfs" template to perform a standard, stack-based traversal.
 /// It automatically manages the visited states and predecessor tracking.
 ///
 /// If a specific `root_vertex_id` is provided, the algorithm explores only the connected component
@@ -124,7 +124,7 @@ result_type<Result, predecessors_map<G>> depth_first_search(
 /// @ingroup GL GL-Algorithm
 /// @brief Executes a concrete recursive Depth-First Search (DFS) traversal over the graph.
 ///
-/// This function relies on the generic @ref gl::algorithm::r_dfs "r_dfs" engine. Instead of a
+/// This function relies on the generic @ref gl::algorithm::r_dfs "r_dfs" template. Instead of a
 /// heap-allocated stack, it utilizes the C++ call stack to navigate the graph.
 ///
 /// > [!WARNING] Call Stack Depth