Added comments related to quasi-topological ordering.

Author: simphotonics

README.md

@@ -59,10 +59,11 @@ Hereby, dashed edges were disregarded since a cyclic graph does not have a topol
 - *Quasi-Topological ordering*: An ordered *sub-set* of graph vertices
 such that v<sub>i</sub>
 occurs before v<sub>j</sub> if there is a directed edge (v<sub>i</sub>, v<sub>j</sub>).
-For a quasi-topological ordering to exist, any two vertices belonging to the *sub-set* must not have mutually connecting edges.
+For a quasi-topological ordering to exist, any two vertices belonging to the *sub-set*
+must not be mutually connected. That is, if there is a path \[v<sub>i</sub>, ...,   v<sub>j</sub>\]
+then there must not be a path \[v<sub>j</sub>, ...,   v<sub>i</sub>\] and vice versa.
 
-
-*Note*: In the context of this package the definition of *edge* might be more lax compared to a
+*Note*: In the context of this package, the definition of *edge* might be more lax compared to a
 rigorous mathematical definition.
 For example, self-loops, that is edges connecting a vertex to itself are explicitly allowed.
 

lib/src/graphs/directed_graph_base.dart

@@ -164,18 +164,14 @@ abstract class DirectedGraphBase<T extends Object> extends Iterable<T> {
   /// including cycles.
   /// * Returns an empty list if no path was found.
   /// * To exclude cycles use the method `shortestPath(start, target)`.
-  List<T> path(T start, T target) {
-    return crawler.path(start, target);
-  }
+  List<T> path(T start, T target) => crawler.path(start, target);
 
   /// Returns all paths from [start] to [target]
   /// including cycles.
   /// * Returns an empty list if no path was found.
   /// * To exclude cycles and list only the shortest paths
   ///   use the method `shortestPaths(start, target)`.
-  List<List<T>> paths(T start, T target) {
-    return crawler.paths(start, target);
-  }
+  List<List<T>> paths(T start, T target) => crawler.paths(start, target);
 
   /// Returns the first cycle detected or an empty list
   /// if the graph is acyclic.
@@ -574,11 +570,12 @@ abstract class DirectedGraphBase<T extends Object> extends Iterable<T> {
   }
 
   /// Returns a set containing the elements of [vertices]
-  /// in quasi topological insertion order if there is not mutual connection
-  /// between any two elements of [vertices].
-  ///
+  /// in quasi-topological insertion order.
   /// * [vertices] must be a subset of the graph vertices. If any vertex in
   /// [vertices] does not belong to the graph, `null` is returned.
+  /// * Note: If A and B are any two elements of [vertices],
+  /// and there is a path [A, ..., B], then there be no path [B, ..., A]
+  ///  for a quasi-topological ordering to exists.
   /// * If sorted is set to
   /// `true` the vertices will be ordered using the graph [comparator] on top
   /// of the topological sort.

lib/src/graphs/graph_crawler.dart

@@ -29,7 +29,9 @@ class GraphCrawler<T extends Object> {
   final Edges<T> edges;
 
   /// Returns the shortest path from [start] to [target].
+  ///
   /// * Returns an empty list if [target] is not reachable from [start].
+  ///
   List<T> path(T start, T target) {
     final tree = <Set<T>>[];
     for (final connected in edges(start)) {
@@ -51,7 +53,7 @@ class GraphCrawler<T extends Object> {
     var startIndex = 0;
     var endIndex = 0;
     var length = tree.length;
-    final visited = HashSet<T>()..add(start);
+    final visited = HashSet<T>();
     do {
       endIndex = tree.length;
       for (var i = startIndex; i < endIndex; ++i) {