Improve documentation for Algorithm\ShortestPath

Author: clue

src/ShortestPath/Base.php

@@ -9,6 +9,45 @@
 use Fhaculty\Graph\Vertex;
 use Fhaculty\Graph\Edge\Base as Edge;
 
+/**
+ * Abstract base class for shortest path algorithms
+ *
+ * This abstract base class provides the base interface for working with
+ * single-source shortest paths (SSSP).
+ *
+ * The shortest path problem is the problem of finding a path between two
+ * vertices such that the sum of the weights of its constituent edges is
+ * minimized. The weight of the shortest path is referred to as distance.
+ *
+ *    A--[10]-------------B---E<--F
+ *     \                 /
+ *      \--[4]--C--[2]--D
+ *
+ * In the above pictured graph, the distance (weight of the shortest path)
+ * between A and C is 4, and the shortest path between A and B is "A->C->D->B"
+ * with a distance (total weight) of 6.
+ *
+ * In graph theory, it is usually assumed that a path to an unreachable vertex
+ * has infinite distance. In the above pictured graph, there's no way path
+ * from A to F, i.e. vertex F is unreachable from vertex A because of the
+ * directed edge "E <- F" pointing in the opposite direction. This library
+ * considers this an Exception instead. So if you're asking for the distance
+ * between A and F, you'll receive an OutOfBoundsException instead.
+ *
+ * In graph theory, it is usually assumed that each vertex has a (pseudo-)path
+ * to itself with a distance of 0. In order to produce reliable, consistent
+ * results, this library considers this (pseudo-)path to be non-existant, i.e.
+ * there's NO "magic" path between A and A. So if you're asking for the distance
+ * between A and A, you'll receive an OutOfBoundsException instead. This allows
+ * us to check hether there's a real path between A and A (cycle via other
+ * vertices) as well as working with loop edges.
+ *
+ * @link http://en.wikipedia.org/wiki/Shortest_path_problem
+ * @link http://en.wikipedia.org/wiki/Tree_%28data_structure%29
+ * @see ShortestPath\Dijkstra
+ * @see ShortestPath\MooreBellmanFord which also supports negative Edge weights
+ * @see ShortestPath\BreadthFirst with does not consider Edge weights, but only the number of hops
+ */
 abstract class Base extends BaseVertex
 {
     /**
@@ -31,8 +70,8 @@ public function getWalkTo(Vertex $endVertex)
      * @param  Vertex    $endVertex
      * @throws OutOfBoundsException if there's no path to the given end vertex
      * @return Edge[]
-     * @uses AlgorithmSp::getEdges()
-     * @uses AlgorithmSp::getEdgesToInternal()
+     * @uses self::getEdges()
+     * @uses self::getEdgesToInternal()
      */
     public function getEdgesTo(Vertex $endVertex)
     {
@@ -46,7 +85,7 @@ public function getEdgesTo(Vertex $endVertex)
      * @param  array     $edges     array of all input edges to operate on
      * @throws OutOfBoundsException if there's no path to the given vertex
      * @return Edge[]
-     * @uses AlgorithmSp::getEdges() if no edges were given
+     * @uses self::getEdges() if no edges were given
      */
     protected function getEdgesToInternal(Vertex $endVertex, array $edges)
     {
@@ -94,7 +133,7 @@ private function sumEdges(array $edges)
      * get array of all vertices the given start vertex has a path to
      *
      * @return Vertex[]
-     * @uses AlgorithmSp::getDistanceMap()
+     * @uses self::getDistanceMap()
      */
     public function getVertices()
     {
@@ -113,7 +152,7 @@ public function getVertices()
      * get array of all vertices' IDs the given start vertex has a path to
      *
      * @return int[]
-     * @uses AlgorithmSp::getDistanceMap()
+     * @uses self::getDistanceMap()
      */
     public function getVerticesId()
     {
@@ -142,9 +181,9 @@ public function hasVertex(Vertex $vertex)
      * get map of vertex IDs to distance
      *
      * @return float[]
-     * @uses AlgorithmSp::getEdges()
-     * @uses AlgorithmSp::getEdgesToInternal()
-     * @uses AlgorithmSp::sumEdges()
+     * @uses self::getEdges()
+     * @uses self::getEdgesToInternal()
+     * @uses self::sumEdges()
      */
     public function getDistanceMap()
     {
@@ -166,8 +205,8 @@ public function getDistanceMap()
      * @param  Vertex    $endVertex
      * @return float
      * @throws OutOfBoundsException if there's no path to the given end vertex
-     * @uses AlgorithmSp::getEdgesTo()
-     * @uses AlgorithmSp::sumEdges()
+     * @uses self::getEdgesTo()
+     * @uses self::sumEdges()
      */
     public function getDistance(Vertex $endVertex)
     {
@@ -177,8 +216,43 @@ public function getDistance(Vertex $endVertex)
     /**
      * create new resulting graph with only edges on shortest path
      *
+     * The resulting Graph will always represent a tree with the start vertex
+     * being the root vertex.
+     *
+     * For example considering the following input Graph with equal weights on
+     * each edge:
+     *
+     *     A----->F
+     *    / \     ^
+     *   /   \   /
+     *  /     \ /
+     *  |      E
+     *  |       \
+     *  |        \
+     *  B--->C<---D
+     *
+     * The resulting shortest path tree Graph will look like this:
+     *
+     *     A----->F
+     *    / \
+     *   /   \
+     *  /     \
+     *  |      E
+     *  |       \
+     *  |        \
+     *  B--->C    D
+     *
+     * Or by just arranging the Vertices slightly different:
+     *
+     *          A
+     *         /|\
+     *        / | \
+     *       B  E  \->F
+     *      /   |
+     *  C<-/    D
+     *
      * @return Graph
-     * @uses AlgorithmSp::getEdges()
+     * @uses self::getEdges()
      * @uses Graph::createGraphCloneEdges()
      */
     public function createGraph()

src/ShortestPath/BreadthFirst.php

@@ -2,15 +2,22 @@
 
 namespace Fhaculty\Graph\Algorithm\ShortestPath;
 
+use Fhaculty\Graph\Vertex;
 use Fhaculty\Graph\Exception\InvalidArgumentException;
-
 use Fhaculty\Graph\Exception\OutOfBoundsException;
 
-use Fhaculty\Graph\Walk;
-
-use Fhaculty\Graph\Vertex;
-use \Exception;
-
+/**
+ * Simple breadth-first shortest path algorithm
+ *
+ * This algorithm ignores edge weights and operates as a level-order algorithm
+ * on the number of hops. As such, it considers the path with the least number
+ * of hops to be shortest.
+ *
+ * This is particularly useful your Graph doesn't have Edge weights assigned to
+ * begin with or if you're merely interested in knowing which Vertices can be
+ * reached at all (path finding). This avoids running expensive operations to
+ * determine the actual weight (distance) of a path.
+ */
 class BreadthFirst extends Base
 {
     /**

src/ShortestPath/Dijkstra.php

@@ -5,12 +5,25 @@
 use Fhaculty\Graph\Exception\UnexpectedValueException;
 use \SplPriorityQueue;
 
+/**
+ * Commonly used Dijkstra's shortest path algorithm
+ *
+ * This is asymptotically the fastest known single-source shortest-path
+ * algorithm for arbitrary graphs with non-negative weights. If your Graph
+ * contains an Edge with negative weight, if will throw an
+ * UnexpectedValueException. Consider using (the slower) MooreBellmanFord
+ * algorithm instead.
+ *
+ * @link http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
+ * @see MooreBellmanFord
+ */
 class Dijkstra extends Base
 {
     /**
      * get all edges on shortest path for this vertex
      *
      * @return Edge[]
+     * @throws UnexpectedValueException when encountering an Edge with negative weight
      */
     public function getEdges()
     {

src/ShortestPath/MooreBellmanFord.php

@@ -7,6 +7,16 @@
 use Fhaculty\Graph\Exception\NegativeCycleException;
 use Fhaculty\Graph\Exception\UnderflowException;
 
+/**
+ * Moore-Bellman-Ford's shortest path algorithm
+ *
+ * It is slower than Dijkstra's algorithm for the same problem, but more
+ * versatile, as it is capable of handling Graphs with negative Edge weights.
+ *
+ * Also known as just "Bellman–Ford algorithm".
+ *
+ * @link http://en.wikipedia.org/wiki/Bellman%E2%80%93Ford_algorithm
+ */
 class MooreBellmanFord extends Base
 {
     /**