diff --git a/README.md b/README.md
index fd203840..ff1ab651 100644
--- a/README.md
+++ b/README.md
@@ -2,16 +2,29 @@
 
 GraPHP is the mathematical graph/network library written in PHP.
 
+**Table of contents**
+
+* [Quickstart examples](#quickstart-examples)
+* [Features](#features)
+* [Components](#components)
+    * [Graph drawing](#graph-drawing)
+    * [Common algorithms](#common-algorithms)
+* [Install](#install)
+* [Tests](#tests)
+* [Contributing](#contributing)
+* [License](#license)
+
 ## Quickstart examples
 
 Once [installed](#install), let's initialize a sample graph:
 
-````php
+```php
 <?php
-require_once 'vendor/autoload.php';
 
 use \Fhaculty\Graph\Graph as Graph;
 
+require_once 'vendor/autoload.php';
+
 $graph = new Graph();
 
 // create some cities
@@ -24,15 +37,16 @@ $cologne->createEdgeTo($madrid);
 $madrid->createEdgeTo($rome);
 // create loop
 $rome->createEdgeTo($rome);
-````
+```
+
+Let's see which city (Vertex) has a road (i.e. an edge pointing) to Rome:
 
-Let's see which city (Vertex) has road (i.e. an edge pointing) to Rome
-````php
+```php
 foreach ($rome->getVerticesEdgeFrom() as $vertex) {
     echo $vertex->getId().' leads to rome'.PHP_EOL;
     // result: Madrid and Rome itself
 }
-````
+```
 
 ## Features
 
diff --git a/src/Edge/Base.php b/src/Edge/Base.php
index 654b3ae9..a93a17ce 100644
--- a/src/Edge/Base.php
+++ b/src/Edge/Base.php
@@ -59,7 +59,7 @@ abstract public function getVerticesStart();
      * return true if this edge is an outgoing edge of the given vertex (i.e. the given vertex is a valid start vertex of this edge)
      *
      * @param  Vertex  $startVertex
-     * @return boolean
+     * @return bool
      * @uses Vertex::getVertexToFrom()
      */
     abstract public function hasVertexStart(Vertex $startVertex);
@@ -68,7 +68,7 @@ abstract public function hasVertexStart(Vertex $startVertex);
      * return true if this edge is an ingoing edge of the given vertex (i . e. the given vertex is a valid end vertex of this edge)
      *
      * @param  Vertex  $targetVertex
-     * @return boolean
+     * @return bool
      * @uses Vertex::getVertexFromTo()
      */
     abstract function hasVertexTarget(Vertex $targetVertex);
@@ -78,7 +78,7 @@ abstract public function isConnection(Vertex $from, Vertex $to);
     /**
      * returns whether this edge is actually a loop
      *
-     * @return boolean
+     * @return bool
      */
     abstract public function isLoop();
 
diff --git a/src/Graph.php b/src/Graph.php
index 97fdaeb1..59c42b2f 100644
--- a/src/Graph.php
+++ b/src/Graph.php
@@ -57,7 +57,7 @@ public function getEdges()
      * create a new Vertex in the Graph
      *
      * @param  int|NULL                 $id              new vertex ID to use (defaults to NULL: use next free numeric ID)
-     * @param  boolean                  $returnDuplicate normal operation is to throw an exception if given id already exists. pass true to return original vertex instead
+     * @param  bool                     $returnDuplicate normal operation is to throw an exception if given id already exists. pass true to return original vertex instead
      * @return Vertex                   (chainable)
      * @throws InvalidArgumentException if given vertex $id is invalid
      * @throws OverflowException        if given vertex $id already exists and $returnDuplicate is not set
@@ -308,7 +308,7 @@ public function getVertex($id)
      * checks whether given vertex ID exists in this graph
      *
      * @param int|string $id identifier of Vertex
-     * @return boolean
+     * @return bool
      */
     public function hasVertex($id)
     {
@@ -320,7 +320,7 @@ public function hasVertex($id)
      *
      * @param  Vertex $vertex instance of the new Vertex
      * @return void
-     * @private
+     * @internal
      * @see self::createVertex() instead!
      */
     public function addVertex(Vertex $vertex)
@@ -336,7 +336,7 @@ public function addVertex(Vertex $vertex)
      *
      * @param  Edge $edge instance of the new Edge
      * @return void
-     * @private
+     * @internal
      * @see Vertex::createEdge() instead!
      */
     public function addEdge(Edge $edge)
@@ -350,7 +350,7 @@ public function addEdge(Edge $edge)
      * @param  Edge                     $edge
      * @return void
      * @throws InvalidArgumentException if given edge does not exist (should not ever happen)
-     * @private
+     * @internal
      * @see Edge::destroy() instead!
      */
     public function removeEdge(Edge $edge)
@@ -369,7 +369,7 @@ public function removeEdge(Edge $edge)
      * @param  Vertex                   $vertex
      * @return void
      * @throws InvalidArgumentException if given vertex does not exist (should not ever happen)
-     * @private
+     * @internal
      * @see Vertex::destroy() instead!
      */
     public function removeVertex(Vertex $vertex)
diff --git a/src/Set/DualAggregate.php b/src/Set/DualAggregate.php
index 7cd2071e..fd23ac8e 100644
--- a/src/Set/DualAggregate.php
+++ b/src/Set/DualAggregate.php
@@ -3,7 +3,7 @@
 namespace Fhaculty\Graph\Set;
 
 /**
- * DualAggregate provides access to both its Vertices and its Edges
+ * A DualAggregate provides access to both its Vertices and its Edges
  *
  * This is the simple base interface for any Graph-like structure / data type
  * which contains a Set of Edges and a Set of Vertices, such as the Graph class
diff --git a/src/Set/Edges.php b/src/Set/Edges.php
index f76fb852..4609ea44 100644
--- a/src/Set/Edges.php
+++ b/src/Set/Edges.php
@@ -197,7 +197,7 @@ public function getEdgeMatch($callbackCheck)
      * checks whethere there's an Edge that matches the given callback filter function
      *
      * @param callable $callbackCheck
-     * @return boolean
+     * @return bool
      * @see self::getEdgeMatch() to return the Edge instance that matches the given callback filter function
      * @uses self::getEdgeMatchOrNull()
      */
@@ -209,7 +209,7 @@ public function hasEdgeMatch($callbackCheck)
     /**
      * get a new set of Edges that match the given callback filter function
      *
-     * This only keeps Edge elements if the $callbackCheck returns a boolean
+     * This only keeps Edge elements if the $callbackCheck returns a bool
      * true and filters out everything else.
      *
      * Edge index positions will be left unchanged.
@@ -229,7 +229,7 @@ public function getEdgesMatch($callbackCheck)
      * Edge index positions will be left unchanged.
      *
      * @param  int                      $orderBy  criterium to sort by. see self::ORDER_WEIGHT, etc.
-     * @param  boolean                  $desc     whether to return biggest first (true) instead of smallest first (default:false)
+     * @param  bool                     $desc     whether to return biggest first (true) instead of smallest first (default:false)
      * @return Edges                    a new Edges set ordered by the given $orderBy criterium
      * @throws InvalidArgumentException if criterium is unknown
      */
@@ -273,7 +273,7 @@ public function getEdgesOrder($orderBy, $desc = false)
      * get first edge ordered by given criterium $orderBy
      *
      * @param  int                      $orderBy  criterium to sort by. see self::ORDER_WEIGHT, etc.
-     * @param  boolean                  $desc     whether to return biggest (true) instead of smallest (default:false)
+     * @param  bool                     $desc     whether to return biggest (true) instead of smallest (default:false)
      * @return Edge
      * @throws InvalidArgumentException if criterium is unknown
      * @throws UnderflowException       if no edges exist
@@ -394,7 +394,7 @@ public function count()
      * A Set if empty if no single Edge instance is added. This is faster
      * than calling `count() === 0`.
      *
-     * @return boolean
+     * @return bool
      */
     public function isEmpty()
     {
diff --git a/src/Set/EdgesAggregate.php b/src/Set/EdgesAggregate.php
index 9ede4983..19e898d2 100644
--- a/src/Set/EdgesAggregate.php
+++ b/src/Set/EdgesAggregate.php
@@ -3,7 +3,7 @@
 namespace Fhaculty\Graph\Set;
 
 /**
- * Basic interface for every class that provides access to its Set of Edges
+ * A basic interface for every class that provides access to its Set of Edges
  */
 interface EdgesAggregate
 {
diff --git a/src/Set/Vertices.php b/src/Set/Vertices.php
index e11a1f06..2bc10540 100644
--- a/src/Set/Vertices.php
+++ b/src/Set/Vertices.php
@@ -113,7 +113,7 @@ public function getVertexId($id)
      * checks whether given vertex ID exists in this set of vertices
      *
      * @param int|string $id identifier of Vertex
-     * @return boolean
+     * @return bool
      * @uses self::hasVertexMatch()
      */
     public function hasVertexId($id)
@@ -199,7 +199,7 @@ public function getVertexMatch($callbackCheck)
      * checks whether there's a Vertex that matches the given callback filter function
      *
      * @param callable $callbackCheck
-     * @return boolean
+     * @return bool
      * @see self::getVertexMatch() to return the Vertex instance that matches the given callback filter function
      * @uses self::getVertexMatchOrNull()
      */
@@ -211,7 +211,7 @@ public function hasVertexMatch($callbackCheck)
     /**
      * get a new set of Vertices that match the given callback filter function
      *
-     * This only keeps Vertex elements if the $callbackCheck returns a boolean
+     * This only keeps Vertex elements if the $callbackCheck returns a bool
      * true and filters out everything else.
      *
      * Vertex index positions will be left unchanged, so if you call this method
@@ -233,7 +233,7 @@ public function getVerticesMatch($callbackCheck)
      * on a VerticesMap, it will also return a VerticesMap.
      *
      * @param  int                      $orderBy  criterium to sort by. see Vertex::ORDER_ID, etc.
-     * @param  boolean                  $desc     whether to return biggest first (true) instead of smallest first (default:false)
+     * @param  bool                     $desc     whether to return biggest first (true) instead of smallest first (default:false)
      * @return Vertices                 a new Vertices set ordered by the given $orderBy criterium
      * @throws InvalidArgumentException if criterium is unknown
      * @see self::getVertexOrder()
@@ -311,7 +311,7 @@ public function getVerticesIntersection($otherVertices)
      * get first vertex (optionally ordered by given criterium $by) from given array of vertices
      *
      * @param  int                      $orderBy  criterium to sort by. see Vertex::ORDER_ID, etc.
-     * @param  boolean                  $desc     whether to return biggest (true) instead of smallest (default:false)
+     * @param  bool                     $desc     whether to return biggest (true) instead of smallest (default:false)
      * @return Vertex
      * @throws InvalidArgumentException if criterium is unknown
      * @throws UnderflowException       if no vertices exist
@@ -422,7 +422,7 @@ public function count()
      * A Set if empty if no single Vertex instance is added. This is faster
      * than calling `count() === 0`.
      *
-     * @return boolean
+     * @return bool
      */
     public function isEmpty()
     {
@@ -432,7 +432,7 @@ public function isEmpty()
     /**
      * check whether this set contains any duplicate vertex instances
      *
-     * @return boolean
+     * @return bool
      * @uses self::getMap()
      */
     public function hasDuplicates()
diff --git a/src/Vertex.php b/src/Vertex.php
index 7c5377f1..baaef2de 100644
--- a/src/Vertex.php
+++ b/src/Vertex.php
@@ -157,7 +157,7 @@ public function createEdge(Vertex $vertex)
      *
      * @param  Edge                     $edge
      * @return void
-     * @private
+     * @internal
      * @see self::createEdge() instead!
      */
     public function addEdge(Edge $edge)
@@ -171,7 +171,7 @@ public function addEdge(Edge $edge)
      * @param  Edge                     $edge
      * @return void
      * @throws InvalidArgumentException if given edge does not exist
-     * @private
+     * @internal
      * @see Edge::destroy() instead!
      */
     public function removeEdge(Edge $edge)
@@ -187,7 +187,7 @@ public function removeEdge(Edge $edge)
      * check whether this vertex has a direct edge to given $vertex
      *
      * @param  Vertex  $vertex
-     * @return boolean
+     * @return bool
      * @uses Edge::hasVertexTarget()
      */
     public function hasEdgeTo(Vertex $vertex)
@@ -203,7 +203,7 @@ public function hasEdgeTo(Vertex $vertex)
      * check whether the given vertex has a direct edge to THIS vertex
      *
      * @param  Vertex  $vertex
-     * @return boolean
+     * @return bool
      * @uses Vertex::hasEdgeTo()
      */
     public function hasEdgeFrom(Vertex $vertex)
diff --git a/src/Walk.php b/src/Walk.php
index e86960db..363a19fa 100644
--- a/src/Walk.php
+++ b/src/Walk.php
@@ -45,7 +45,7 @@ public static function factoryFromEdges($edges, Vertex $startVertex)
      *
      * @param  Vertices|Vertex[]  $vertices
      * @param  int|null           $by
-     * @param  boolean            $desc
+     * @param  bool               $desc
      * @return Walk
      * @throws UnderflowException if no vertices were given
      * @see Edges::getEdgeOrder() for parameters $by and $desc
@@ -80,7 +80,7 @@ public static function factoryFromVertices($vertices, $by = null, $desc = false)
      * @param  Vertex[]           $predecessors map of vid => predecessor vertex instance
      * @param  Vertex             $vertex       start vertex to search predecessors from
      * @param  int|null           $by
-     * @param  boolean            $desc
+     * @param  bool               $desc
      * @return Walk
      * @throws UnderflowException
      * @see Edges::getEdgeOrder() for parameters $by and $desc
@@ -130,7 +130,7 @@ public static function factoryCycleFromPredecessorMap(array $predecessors, Verte
      *
      * @param  Vertex[]|Vertices  $vertices
      * @param  int|null           $by
-     * @param  boolean            $desc
+     * @param  bool               $desc
      * @return Walk
      * @throws UnderflowException if no vertices were given
      * @see Edges::getEdgeOrder() for parameters $by and $desc
@@ -283,7 +283,7 @@ public function getAlternatingSequence()
     /**
      * check to make sure this walk is still valid (i.e. source graph still contains all vertices and edges)
      *
-     * @return boolean
+     * @return bool
      * @uses Walk::getGraph()
      * @uses Graph::getVertices()
      * @uses Graph::getEdges()