Update documentation

Author: korthaj

example_dfs_test.go

@@ -64,7 +64,8 @@ func (d *DFSData) dfsVisit(g graph.Iterator, v int) {
 	d.Finish[v] = d.Time
 }
 
-// An implementation of DFS demonstrating how to use this package.
+// An implementation of depth-first search
+// demonstrating how to use this package.
 func Example_dFS() {
 	// Build a small directed graph:
 	//

examples_test.go

@@ -17,11 +17,11 @@ func Example_basics() {
 	g.AddBoth(1, 3)
 
 	// The vertices of all graphs in this package are numbered 0..n-1.
-	// The edge iterator is a method called Visit; it calls
-	// a do function for each neighbor of a given vertex. Together
-	// with the Order method—which returns the number of vertices
-	// in a graph—it constitutes an Iterator. All algorithms in this
-	// package operate on any graph implementing this interface.
+	// The edge iterator is a method called Visit; it calls a function
+	// for each neighbor of a given vertex. Together with the Order
+	// method — which returns the number of vertices in a graph — it
+	// constitutes an Iterator. All algorithms in this package operate
+	// on any graph implementing this interface.
 
 	// Visit all edges of a graph.
 	for v := 0; v < g.Order(); v++ {
@@ -118,9 +118,8 @@ func ExampleEulerDirected() {
 	g.AddBoth(0, 1)
 	g.Add(1, 2)
 
-	walk, _ := graph.EulerDirected(g)
-	fmt.Println(walk)
-	// Output: [1 0 1 2]
+	fmt.Println(graph.EulerDirected(g))
+	// Output: [1 0 1 2] true
 }
 
 // Find an Euler walk in an undirected graph.
@@ -135,10 +134,9 @@ func ExampleEulerUndirected() {
 	g.AddBoth(2, 3)
 	g.AddBoth(3, 3)
 
-	walk, _ := graph.EulerUndirected(g)
-	fmt.Println(walk)
+	fmt.Println(graph.EulerUndirected(g))
 	// Output:
-	// [1 3 3 2]
+	// [1 3 3 2] true
 }
 
 // Find a shortest path between two vertices in a graph.

graph.go

@@ -2,9 +2,10 @@
 //
 // Generic graph algorithms
 //
-// The algorithms can be applied to any graph data structure implementing
-// the two Iterator methods: Order, which returns the number of vertices,
-// and Visit, which iterates over the neighbors of a vertex.
+// The algorithms in this library can be applied to any graph data
+// structure implementing the two Iterator methods: Order, which returns
+// the number of vertices, and Visit, which iterates over the neighbors
+// of a vertex.
 //
 // All algorithms operate on directed graphs with a fixed number
 // of vertices, labeled from 0 to n-1, and edges with integer cost.
@@ -77,7 +78,7 @@ type edge struct {
 }
 
 // String returns a description of g with two elements:
-// the number of vertices, followed by a list of all edges.
+// the number of vertices, followed by a sorted list of all edges.
 func String(g Iterator) string {
 	n := g.Order()
 	// This may be a multigraph, so we look for duplicates by counting.

immutable.go

@@ -118,12 +118,12 @@ func (g *Immutable) VisitFrom(v int, a int, do func(w int, c int64) bool) bool {
 	return false
 }
 
-// String returns a string representation of this graph.
+// String returns a string representation of the graph.
 func (g *Immutable) String() string {
 	return String(g)
 }
 
-// Order returns the number of vertices in this graph.
+// Order returns the number of vertices in the graph.
 func (g *Immutable) Order() int {
 	return len(g.edges)
 }

maxflow.go

@@ -2,8 +2,8 @@ package graph
 
 // MaxFlow computes a maximum flow from s to t in a graph
 // with nonnegative edge capacities.
-// The time complexity is O(|V|⋅|E|²), where |V| is the number of vertices
-// and |E| the number of edges in the graph.
+// The time complexity is O(|E|²⋅|V|), where |E| is the number of edges
+// and |V| the number of vertices in the graph.
 func MaxFlow(g Iterator, s, t int) (flow int64, graph Iterator) {
 	// Edmonds-Karp's algorithm
 	n := g.Order()

mutable.go

@@ -70,12 +70,12 @@ func copyImmutable(g *Immutable) *Mutable {
 	return h
 }
 
-// String returns a string representation of this graph.
+// String returns a string representation of the graph.
 func (g *Mutable) String() string {
 	return String(g)
 }
 
-// Order returns the number of vertices in this graph.
+// Order returns the number of vertices in the graph.
 func (g *Mutable) Order() int {
 	return len(g.edges)
 }

top.go

@@ -10,7 +10,7 @@ func TopSort(g Iterator) (order []int, ok bool) {
 	return
 }
 
-// Acyclic returns true if g has no cycles.
+// Acyclic tells if g has no cycles.
 func Acyclic(g Iterator) bool {
 	_, acyclic := topsort(g, false)
 	return acyclic

weak.go

@@ -1,6 +1,6 @@
 package graph
 
-// Connected returns true if g has exactly one (weakly) connected component.
+// Connected tells if g has exactly one (weakly) connected component.
 func Connected(g Iterator) bool {
 	_, count := components(g)
 	return count == 1