Update documentation

Author: Stefan Nilsson

build/build.go

@@ -68,15 +68,15 @@ type Virtual struct {
 	visit  func(v int, a int, do func(w int, c int64) (skip bool)) (aborted bool)
 }
 
-// FilterFunc is a function that tells if there is an edge from v to w.
+// FilterFunc is a function that tells if there is a directed edge from v to w.
 // The nil value represents an edge functions that always returns true.
 type FilterFunc func(v, w int) bool
 
 // CostFunc is a function that computes the cost of an edge from v to w.
 // The nil value represents a cost function that always returns 0.
 type CostFunc func(v, w int) int64
 
-// Cost returns a CostFunc which always returns n.
+// Cost returns a CostFunc that always returns n.
 func Cost(n int64) CostFunc {
 	return func(int, int) int64 { return n }
 }
@@ -432,7 +432,7 @@ func (g *Virtual) AddCostFunc(c CostFunc) *Virtual {
 	return &res
 }
 
-// Order returns the number of vertices in this graph.
+// Order returns the number of vertices in the graph.
 func (g *Virtual) Order() int {
 	return g.order
 }

build/cartesian.go

@@ -2,7 +2,7 @@ package build
 
 import "strconv"
 
-// Cartesian returns the cartesian product of g1 and g2;
+// Cartesian returns the cartesian product of g1 and g2:
 // a graph whose vertices correspond to ordered pairs (v1, v2),
 // where v1 and v2 are vertices in g1 and g2, respectively.
 // The vertices (v1, v2) and (w1, w2) are connected by an edge if

build/cycle.go

@@ -1,7 +1,7 @@
 package build
 
-// Cycle returns a virtual cycle graph with the edges
-// {0, 1}, {1, 2}, {2, 3},... , {n-1, 0}.
+// Cycle returns a virtual cycle graph with n vertices and
+// the edges {0, 1}, {1, 2}, {2, 3},... , {n-1, 0}.
 func Cycle(n int) *Virtual {
 	switch {
 	case n < 0:

build/edgeset.go

@@ -24,7 +24,7 @@ func NoEdges() EdgeSet {
 	}
 }
 
-// Edge returns a set consisting of the single edge {v, w}, where v ≠ w.
+// Edge returns a set consisting of a single edge {v, w}, v ≠ w, of zero cost.
 func Edge(v, w int) EdgeSet {
 	if v < 0 || w < 0 || v == w {
 		return NoEdges()
@@ -35,7 +35,7 @@ func Edge(v, w int) EdgeSet {
 	}
 }
 
-// Contains tells if the set contains the edge from v to w.
+// Contains tells if the set contains the edge {v, w}.
 func (e EdgeSet) Contains(v, w int) bool {
 	switch {
 	case e.Keep != nil && !e.Keep(v, w):

build/examples_test.go

@@ -10,10 +10,10 @@ import (
 // Find a shortest path going back and forth between
 // two sets of points in the plane.
 func Example_euclid() {
-	type point struct{ x, y int }
+	type Point struct{ x, y int }
 
 	// Euclidean distance.
-	euclid := func(p, q point) float64 {
+	Euclid := func(p, q Point) float64 {
 		xd := p.x - q.x
 		yd := p.y - q.y
 		return math.Sqrt(float64(xd*xd + yd*yd))
@@ -22,7 +22,7 @@ func Example_euclid() {
 	// 0     3
 	// 1     4
 	// 2     5
-	points := []point{
+	points := []Point{
 		{0, 0}, {0, 1}, {0, 2},
 		{4, 0}, {4, 1}, {4, 2},
 	}
@@ -32,7 +32,7 @@ func Example_euclid() {
 	// and then apply a cost function to the edges of the graph.
 	g := build.Kmn(3, 3).AddCostFunc(func(v, w int) int64 {
 		// Distance to three decimal places.
-		return int64(1000 * euclid(points[v], points[w]))
+		return int64(1000 * Euclid(points[v], points[w]))
 	})
 
 	// Find a shortest path from 0 to 2.

build/grid.go

@@ -2,10 +2,10 @@ package build
 
 import "strconv"
 
-// Grid returns a virtual graph whose vertices correspond to points in the plane
-// with integer coordinates, y-coordinates being in the range 0..m-1,
-// and x-coordinates in the range 0..n-1. Two vertices are connected
-// by an edge whenever the corresponding points are at distance 1.
+// Grid returns a virtual graph whose vertices correspond to integer
+// points in the plane: y-coordinates being in the range 0..m-1,
+// and x-coordinates in the range 0..n-1. Two vertices of a grid
+// are adjacent whenever the corresponding points are at distance 1.
 //
 // Point (x, y) gets index nx + y, and index i corresponds to the point (i/n, i%n).
 func Grid(m, n int) *Virtual {

build/match.go

@@ -3,7 +3,7 @@ package build
 // Match connects g1 to g2 by matching vertices in g1 with vertices in g2.
 // Only vertices belonging to the bridge are included,
 // and the vertices are matched in numerical order.
-// The vertices of g2 are renumbered before the operation:
+// The vertices of g2 are renumbered before the matching:
 // vertex v ∊ g2 becomes v + g1.Order() in the new graph.
 func (g1 *Virtual) Match(g2 *Virtual, bridge EdgeSet) *Virtual {
 	n := g1.order + g2.order

build/tensor.go

@@ -2,7 +2,7 @@ package build
 
 import "strconv"
 
-// Tensor returns the tensor product of g1 and g2;
+// Tensor returns the tensor product of g1 and g2:
 // a graph whose vertices correspond to ordered pairs (v1, v2),
 // where v1 and v2 are vertices in g1 and g2, respectively.
 // The vertices (v1, v2) and (w1, w2) are connected by an edge whenever

build/vertexset.go

@@ -3,8 +3,8 @@ package build
 import "sort"
 
 // VertexSet represents a set of vertices in a graph.
-// The zero value of a VertexSet is the universe,
-// which represents all vertices in a graph.
+// The zero value of a VertexSet is the universe;
+// the set containing all vertices.
 type VertexSet struct {
 	// A set is an immutable sorted list of non-empty disjoint intervals.
 	// The zero value VertexSet{nil} represents the universe.
@@ -90,7 +90,7 @@ func (s VertexSet) rank(n int) int {
 	return in.index + n - in.a
 }
 
-// Contains tells if v is a member of set s.
+// Contains tells if v is a member of the set.
 func (s VertexSet) Contains(v int) bool {
 	switch {
 	case s.set == nil: