docs: Enhance documentation for Tarjan's Algorithm components with detailed method descriptions

Author: weilycoder

weilycoder/graph/tarjan.hpp

@@ -1,13 +1,22 @@
 #ifndef WEILYCODER_TARJAN_HPP
 #define WEILYCODER_TARJAN_HPP
 
+/**
+ * @file tarjan.hpp
+ * @brief Tarjan's Algorithm for Graph Connected Problems
+ */
+
 #include <algorithm>
 #include <cstddef>
 #include <stack>
 #include <utility>
 #include <vector>
 
 namespace weilycoder {
+/**
+ * @brief Strongly Connected Components using Tarjan's Algorithm
+ * @tparam ptr_t Type for representing indices (default: size_t)
+ */
 template <typename ptr_t = size_t> struct StrongConnectedComponents {
   ptr_t dfs_time = 0;
 
@@ -18,11 +27,24 @@ template <typename ptr_t = size_t> struct StrongConnectedComponents {
 
   std::vector<std::vector<ptr_t>> sccs;
 
+  /**
+   * @brief Constructs a StrongConnectedComponents for n nodes
+   * @param n Number of nodes
+   */
   StrongConnectedComponents(ptr_t n)
       : in_stack(n, false), dfn(n, 0), low(n, 0), graph(n) {}
 
+  /**
+   * @brief Adds a directed edge from u to v
+   * @param u Source node
+   * @param v Destination node
+   */
   void add_edge(ptr_t u, ptr_t v) { graph[u].push_back(v); }
 
+  /**
+   * @brief Tarjan's DFS to find SCCs
+   * @param u Current node
+   */
   void tarjan(ptr_t u) {
     dfn[u] = low[u] = ++dfs_time;
     stk.push(u), in_stack[u] = true;
@@ -45,6 +67,10 @@ template <typename ptr_t = size_t> struct StrongConnectedComponents {
     }
   }
 
+  /**
+   * @brief Solves for all SCCs in the graph, sorting them in DFS order,
+   *      i.e., if there is an edge from SCC A to SCC B, then A appears before B
+   */
   void solve() {
     for (size_t i = 0; i < graph.size(); ++i)
       if (!dfn[i])
@@ -53,6 +79,10 @@ template <typename ptr_t = size_t> struct StrongConnectedComponents {
   }
 };
 
+/**
+ * @brief Two-Edge Connected Components using Tarjan's Algorithm
+ * @tparam ptr_t Type for representing indices (default: size_t)
+ */
 template <typename ptr_t = size_t> struct TwoEdgeConnectedComponents {
   ptr_t dfs_time = 0, edge_time = 1;
 
@@ -63,15 +93,29 @@ template <typename ptr_t = size_t> struct TwoEdgeConnectedComponents {
 
   std::vector<std::vector<ptr_t>> eccs;
 
+  /**
+   * @brief Constructs a TwoEdgeConnectedComponents for n nodes
+   * @param n Number of nodes
+   */
   TwoEdgeConnectedComponents(ptr_t n)
       : in_stack(n, false), dfn(n, 0), low(n, 0), graph(n) {}
 
+  /**
+   * @brief Adds an undirected edge between u and v
+   * @param u One endpoint
+   * @param v Other endpoint
+   */
   void add_edge(ptr_t u, ptr_t v) {
     graph[u].emplace_back(v, edge_time);
     graph[v].emplace_back(u, edge_time);
     edge_time++;
   }
 
+  /**
+   * @brief Tarjan's DFS to find 2-edge connected components
+   * @param u Current node
+   * @param parent_edge Edge ID of the edge leading to u
+   */
   void tarjan(ptr_t u, ptr_t parent_edge) {
     dfn[u] = low[u] = ++dfs_time;
     stk.push(u), in_stack[u] = true;
@@ -96,13 +140,20 @@ template <typename ptr_t = size_t> struct TwoEdgeConnectedComponents {
     }
   }
 
+  /**
+   * @brief Solves for all 2-edge connected components in the graph
+   */
   void solve() {
     for (size_t i = 0; i < graph.size(); ++i)
       if (!dfn[i])
         tarjan(i, 0);
   }
 };
 
+/**
+ * @brief Biconnected Components using Tarjan's Algorithm
+ * @tparam ptr_t Type for representing indices (default: size_t)
+ */
 template <typename ptr_t = size_t> struct BiconnectedComponents {
   ptr_t dfs_time = 0;
 
@@ -113,14 +164,28 @@ template <typename ptr_t = size_t> struct BiconnectedComponents {
   std::vector<bool> is_cut;
   std::vector<std::vector<ptr_t>> dccs;
 
+  /**
+   * @brief Constructs a BiconnectedComponents for n nodes
+   * @param n Number of nodes
+   */
   BiconnectedComponents(ptr_t n)
       : dfn(n, 0), low(n, 0), graph(n), is_cut(n, false) {}
 
+  /**
+   * @brief Adds an undirected edge between u and v
+   * @param u One endpoint
+   * @param v Other endpoint
+   */
   void add_edge(ptr_t u, ptr_t v) {
     graph[u].push_back(v);
     graph[v].push_back(u);
   }
 
+  /**
+   * @brief Tarjan's DFS to find biconnected components
+   * @param u Current node
+   * @param is_root Whether u is the root of the DFS tree
+   */
   void tarjan(ptr_t u, bool is_root) {
     dfn[u] = low[u] = ++dfs_time, stk.push(u);
 
@@ -148,6 +213,9 @@ template <typename ptr_t = size_t> struct BiconnectedComponents {
     }
   }
 
+  /**
+   * @brief Solves for all biconnected components in the graph
+   */
   void solve() {
     for (size_t i = 0; i < graph.size(); ++i)
       if (!dfn[i])