pfs fix + dijkstra alignment and docs + template docs alignment

Author: SpectraL519

Doxyfile

@@ -289,7 +289,7 @@ TAB_SIZE               = 4
 # with the commands \{ and \} for these it is advised to use the version @{ and
 # @} or use a double escape (\\{ and \\})
 
-ALIASES                =
+ALIASES                = hideparams="@xmlonly <hideparams/> @endxmlonly"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For

include/gl/algorithm/pathfinding/dijkstra.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/pathfinding/dijkstra.hpp
+/// @brief Concrete implementation of Dijkstra's single-source shortest path algorithm and path reconstruction utilities.
+
 #pragma once
 
 #include "gl/algorithm/core.hpp"
@@ -10,30 +13,117 @@
 #include "gl/constants.hpp"
 #include "gl/types/core.hpp"
 
-#include <deque>
-
 namespace gl::algorithm {
 
+/// @ingroup GL GL-Algorithm
+/// @brief A descriptor structure holding the results of a single-source shortest path execution.
+///
+/// ### Template Parameters
+/// | Parameter | Description | Constraint |
+/// | :-------- | :--- | :--- |
+/// | G | The type of the graph. | Must satisfy the [**c_graph**](gl_concepts.md#gl-traits-c-graph) concept. |
+/// | VertexDistanceType | The numeric type used to represent accumulated path weights/distances. | Must satisfy the [**c_arithmetic**](gl_concepts.md#gl-traits-c-arithmetic) concept. |
 template <traits::c_graph G, traits::c_arithmetic VertexDistanceType>
 struct paths_descriptor {
     using id_type = typename G::id_type;
     using distance_type = VertexDistanceType;
 
+    /// @brief Constructs a descriptor sized for the given number of vertices.
+    /// @param n_vertices The total number of vertices in the graph.
     paths_descriptor(const size_type n_vertices)
     : predecessors(n_vertices, invalid_id), distances(n_vertices) {}
 
+    /// @brief The predecessor map tracking the optimal path tree.
     predecessors_map<G> predecessors;
+    /// @brief The accumulated shortest distances to each vertex from the source.
     std::vector<distance_type> distances;
 };
 
+/// @ingroup GL GL-Algorithm
+/// @brief An alias for @ref gl::algorithm::paths_descriptor "paths_descriptor" that automatically deduces the appropriate distance type for the graph.
+/// @tparam G The type of the graph.
 template <traits::c_graph G>
 using paths_descriptor_type = paths_descriptor<G, vertex_distance_type<G>>;
 
+/// @ingroup GL GL-Algorithm
+/// @brief Factory function to create an initialized paths descriptor sized for the given graph.
+/// @tparam G The type of the graph.
+/// @param graph The graph to size the descriptor against.
+/// @return A @ref gl::algorithm::paths_descriptor "paths_descriptor" initialized with invalid predecessors and default-constructed distances.
 template <traits::c_graph G>
 [[nodiscard]] gl_attr_force_inline paths_descriptor_type<G> make_paths_descriptor(const G& graph) {
     return paths_descriptor_type<G>{graph.n_vertices()};
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Internal node structure for Dijkstra's algorithm to snapshot distances and preserve heap invariants.
+///
+/// This structure is used in the @ref gl::algorithm::dijkstra_shortest_paths "dijkstra_shortest_paths" algorithm
+/// to capture the state of a vertex at the moment it is enqueued, ensuring that the priority queue remains stable
+/// even if the global distance map is updated during traversal.
+///
+/// @tparam G The type of the graph. Must satisfy the [**c_graph**](gl_concepts.md#gl-traits-c-graph) concept.
+template <traits::c_graph G>
+struct dijkstra_search_node {
+    /// @brief The type of the vertex ID.
+    using id_type = typename G::id_type;
+
+    id_type vertex_id; ///< @brief The ID of the vertex represented by this node.
+    id_type pred_id; ///< The ID of the predecessor vertex used to reach this node.
+    vertex_distance_type<G>
+        distance; ///< The accumulated distance from the source to this vertex at the time of enqueueing.
+};
+
+/// @ingroup GL GL-Algorithm
+/// @brief Computes the shortest paths from a single source vertex to all reachable vertices using Dijkstra's algorithm.
+///
+/// This algorithm utilizes the generic @ref gl::algorithm::pfs "pfs" template using the dedicated
+/// @ref gl::algorithm::dijkstra_search_node "serch node type" to perform a priority-first search based
+/// on accumulated edge weights. It strictly requires non-negative edge weights; if a negative weight is
+/// encountered during traversal, the algorithm immediately throws an exception.
+///
+/// ### Example Usage
+/// ```cpp
+/// auto paths = gl::algorithm::dijkstra_shortest_paths(graph, source_id); // (1)!
+///
+/// auto path_to_target
+///     = gl::algorithm::reconstruct_path(paths.predecessors, target_id); // (2)!
+/// std::cout << "Path: "
+///           << gl::io::range_formatter(path_to_target, " -> ", "", "") // (3)!
+///           << "\nDistance: " << paths.distances[target_id] << '\n'; // (4)!
+/// ```
+///
+/// 1\. Executes the shortest path calculation from the given `source_id`.
+///
+/// 2\. Reconstructs the exact sequence of vertices from the source to the `target_id` using the @ref gl::algorithm::reconstruct_path "reconstruct_path" function.
+///
+/// 3\. Prints the path to the target vertex using the @ref gl::io::range_formatter "range_formatter" helper.
+///
+/// 4\. Retrievs the total distance to the target vertex from the @ref gl::algorithm::paths_descriptor "paths descriptor" object returned by Dijkstra's algorithm.
+///
+/// > [!INFO] Algorithmic Complexity
+/// >
+/// > The time complexity depends on the underlying representation of `GraphType` and the priority queue overhead:
+/// > - **Adjacency List Representations**: \f$O((|V| + |E|) \log |V|)\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 + |E| \log |V|)\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 | Constraint |
+/// | :-------- | :--- | :--- |
+/// | G | The type of the graph being traversed. Must define a valid distance/weight property. | 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" |
+///
+/// @param graph The graph to evaluate.
+/// @param source_id The starting vertex ID for the shortest path calculation.
+/// @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 A @ref gl::algorithm::paths_descriptor "paths_descriptor" containing the accumulated distances and predecessor map.
+/// @throws std::invalid_argument If an edge with a negative weight is encountered.
+/// @hideparams
 template <
     traits::c_graph G,
     traits::c_optional_callback<void, typename G::id_type> PreVisitCallback = empty_callback,
@@ -55,19 +145,27 @@ template <
 
     std::optional<edge_type> negative_edge;
 
+    // Seed the queue with the custom snapshot node
+    std::vector<dijkstra_search_node<G>> init_queue{
+        {source_id, source_id, distance_type{}}
+    };
+
     pfs(
         graph,
-        [&paths](const search_node<G>& lhs, const search_node<G>& rhs) {
-            return paths.distances[lhs.vertex_id] > paths.distances[rhs.vertex_id];
+        [](const dijkstra_search_node<G>& lhs, const dijkstra_search_node<G>& rhs
+        ) { // pq comparator
+            return lhs.distance > rhs.distance;
+        },
+        init_queue,
+        [&paths](const dijkstra_search_node<G>& node) { // visit_vertex_pred (stale node rejection)
+            return node.distance <= paths.distances[to_idx(node.vertex_id)];
         },
-        init_range<G>(source_id),
-        empty_callback{}, // visit predicate
         empty_callback{}, // visit callback
         [&paths, &negative_edge](id_type vertex_id, const edge_type& in_edge)
             -> decision { // enqueue predicate
             const auto pred_id = in_edge.other(vertex_id);
-
             const auto edge_weight = get_weight<G>(in_edge);
+
             if (edge_weight < 0) {
                 negative_edge.emplace(in_edge);
                 return decision::abort;
@@ -85,6 +183,9 @@ template <
 
             return false;
         },
+        [&paths](id_type target_id, id_type pred_id, const edge_type&) { // make_node callback
+            return dijkstra_search_node<G>{target_id, pred_id, paths.distances[to_idx(target_id)]};
+        },
         pre_visit,
         post_visit
     );
@@ -102,26 +203,44 @@ template <
     return paths;
 }
 
+/// @ingroup GL GL-Algorithm
+/// @brief Reconstructs the sequence of vertices forming a path to a specific target.
+///
+/// This utility walks backward through a predecessor map, starting from the `vertex_id`
+/// until it reaches the root vertex (a vertex that is its own predecessor).
+///
+/// ### Template Parameters
+/// | Parameter | Description | Constraint |
+/// | :-------- | :--- | :--- |
+/// | IdType | The type of the vertex IDs. | Must satisfy the [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) concept. |
+/// | IdRange | The type of the random-access range containing the predecessor map. | Must satisfy the [**c_random_access_range_of**](gl_concepts.md#gl-traits-c-random-access-range-of) concept for `IdType`. |
+///
+/// @param predecessor_map The predecessor map generated by a traversal algorithm (e.g., BFS, DFS, Dijkstra).
+/// @param vertex_id The target vertex ID to reconstruct the path for.
+/// @return A `std::vector` containing the sequence of vertex IDs from the source to the target.
+/// @throws std::invalid_argument If the target `vertex_id` is unreachable (its predecessor is invalid).
+/// @hideparams
 template <traits::c_id_type IdType, traits::c_random_access_range_of<IdType> IdRange>
-[[nodiscard]] std::deque<IdType> reconstruct_path(
+[[nodiscard]] std::vector<IdType> reconstruct_path(
     const IdRange& predecessor_map, const IdType vertex_id
 ) {
     if (not is_reachable(predecessor_map, vertex_id))
         throw std::invalid_argument(
             std::format("[alg::reconstruct_path] The given vertex is unreachable: {}", vertex_id)
         );
 
-    std::deque<IdType> path;
-    IdType current_vertex = vertex_id;
+    std::vector<IdType> path;
+    auto curr = vertex_id;
 
     while (true) {
-        path.push_front(current_vertex);
-        IdType predecessor = predecessor_map[to_idx(current_vertex)];
-        if (predecessor == current_vertex)
+        path.push_back(curr);
+        auto pred = predecessor_map[to_idx(curr)];
+        if (pred == curr)
             break;
-        current_vertex = predecessor;
+        curr = pred;
     }
 
+    std::ranges::reverse(path);
     path.shrink_to_fit();
     return path;
 }

include/gl/algorithm/templates/bfs.hpp

@@ -29,9 +29,9 @@ namespace gl::algorithm {
 ///
 /// bool completed = gl::algorithm::bfs(
 ///     graph,
-///     gl::algorithm::init_range<graph_type>(start_id),        // (2)!
+///     gl::algorithm::init_range<graph_type>(start_id), // (2)!
 ///     gl::algorithm::default_visit_vertex_predicate(visited), // (3)!
-///     [&](auto v, auto p) {                                   // (4)!
+///     [&](auto v, auto p) { // (4)!
 ///         std::cout << "Visited vertex " << v << '\n';
 ///         return true; // Continue search
 ///     },
@@ -50,15 +50,15 @@ namespace gl::algorithm {
 /// 5\. Predicate ensuring we only enqueue adjacent vertices that haven't been visited yet, returning a @ref gl::algorithm::decision "decision".
 ///
 /// ### Template Parameters
-/// | Parameter | Description |
-/// | :-------- | :--- |
-/// | G | The type of the graph being traversed. |
-/// | InitQueueRangeType | The type of the container providing the initial roots to enqueue. |
-/// | VisitVertexPredicate | Type of the callable deciding if a popped vertex should be processed. |
-/// | VisitCallback | Type of the callable executed when a vertex is officially visited. |
-/// | EnqueueVertexPred | Type of the callable deciding if an adjacent vertex should be pushed to the queue. |
-/// | PreVisitCallback | Type of the callable executed immediately before `VisitCallback`. |
-/// | PostVisitCallback | Type of the callable executed after all adjacent edges are evaluated. |
+/// | Parameter | Description | Constraint |
+/// | :-------- | :--- | :--- |
+/// | G | The type of the graph being traversed. | Must satisfy the [**c_graph**](gl_concepts.md#gl-traits-c-graph) concept. |
+/// | InitQueueRangeType | The type of the container providing the initial roots to enqueue. | Must be a *forward range* of @ref gl::algorithm::search_node "search nodes". |
+/// | VisitVertexPredicate | Type of the callable deciding if a popped vertex should be processed. | Must be one of:<br/>- An `(id_type) -> bool` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |
+/// | VisitCallback | Type of the callable executed when a vertex is officially visited. | Must be one of:<br/>- An `(id_type, id_type) -> bool` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |
+/// | EnqueueVertexPred | Type of the callable deciding if an adjacent vertex should be pushed to the queue. | Must be one of:<br/>- An `(id_type, const edge_type&) -> decision` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |
+/// | PreVisitCallback | Type of the callable executed immediately before `VisitCallback`. | Must be one of:<br/>- An `(id_type) -> void` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |
+/// | PostVisitCallback | Type of the callable executed after all adjacent edges are evaluated. | Must be one of:<br/>- An `(id_type) -> void` callable<br/>- An @ref gl::algorithm::empty_callback "empty_callback" |
 ///
 /// @param graph The graph to traverse.
 /// @param initial_queue_content A range of initial @ref gl::algorithm::search_node "search nodes" to seed the BFS queue.
@@ -71,6 +71,7 @@ namespace gl::algorithm {
 /// @param pre_visit Hook executed immediately before the `visit` callback.
 /// @param post_visit Hook executed after all adjacent edges of the current vertex have been evaluated.
 /// @return `true` if the queue was exhausted naturally, `false` if the search was aborted early by a callback or predicate.
+/// @hideparams
 template <
     traits::c_graph G,
     traits::c_forward_range_of<search_node<G>> InitQueueRangeType = std::vector<search_node<G>>,