Docs for BFS-based shortest path search

docs/docs/algorithms/shortest-path/bfs-based-shortest-path.md

@@ -2,4 +2,28 @@
 sidebar_position: 1
 ---
 
-# BFS Based Shortest Path
+# BFS Based Shortest Path
+Breadth-First Search (BFS) is a graph traversal algorithm that efficiently finds the shortest
+path between two vertices in an **unweighted graph** by exploring vertices level by level,
+guaranteeing the shortest path, and has a time complexity of `O(|E| + |V|)`,
+where `|V|` is the number of vertices and `|E|` is the number of edges in the graph.
+BFS uses a queue to iteratively visit neighboring vertices from the source
+vertex, ensuring that the shortest path is discovered before longer paths.
+
+[wikipedia](https://en.wikipedia.org/wiki/Breadth-first_search)
+
+## Syntax
+
+Calculates the shortest path between one start_vertex and one
+end_vertex using BFS. This does not consider edge weights.
+
+```cpp
+template <typename V, typename E, graph_type T, typename WEIGHT_T = decltype(get_weight(std::declval<E>()))>
+std::optional<graph_path<WEIGHT_T>> bfs_shortest_path(
+    const graph<V, E, T>& graph, vertex_id_t start_vertex, vertex_id_t end_vertex);
+```
+
+- **graph** The graph to extract shortest path from.
+- **start_vertex** Vertex id where the shortest path should start.
+- **end_vertex** Vertex id where the shortest path should end.
+- **return** An optional with the shortest path (list of vertices) if found.

include/graaflib/algorithm/shortest_path.h

@@ -20,12 +20,13 @@ struct graph_path {
 };
 
 /**
- * @brief calculates the shortest path between on start_vertex and one
+ * @brief calculates the shortest path between one start_vertex and one
  * end_vertex using BFS. This does not consider edge weights.
  *
  * @param graph The graph to extract shortest path from.
  * @param start_vertex Vertex id where the shortest path should start.
  * @param end_vertex Vertex id where the shortest path should end.
+ * @return An optional with the shortest path (list of vertices) if found.
  */
 template <typename V, typename E, graph_type T,
           typename WEIGHT_T = decltype(get_weight(std::declval<E>()))>
@@ -34,7 +35,7 @@ std::optional<graph_path<WEIGHT_T>> bfs_shortest_path(
     vertex_id_t end_vertex);
 
 /**
- * @brief calculates the shortest path between on start_vertex and one
+ * @brief calculates the shortest path between one start_vertex and one
  * end_vertex using Dijkstra's algorithm. Works on both weighted as well as
  * unweighted graphs. For unweighted graphs, a unit weight is used for each
  * edge.