From b8a214bd941babe6a219ba01af57be87beadf254 Mon Sep 17 00:00:00 2001
From: Andrew Dunham <andrew@du.nham.ca>
Date: Tue, 14 Apr 2015 15:34:41 -0700
Subject: [PATCH] Initial work at documenting new Go API

---
 graph/path/path.go | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/graph/path/path.go b/graph/path/path.go
index b25cac4..02df44b 100644
--- a/graph/path/path.go
+++ b/graph/path/path.go
@@ -26,17 +26,22 @@ type morphism struct {
 	Apply    graph.ApplyMorphism
 }
 
+// Path represents either a morphism (a pre-defined path stored for later use),
+// or a concrete path, consisting of a morphism and an underlying QuadStore.
 type Path struct {
 	stack []morphism
 	qs    graph.QuadStore // Optionally. A nil qs is equivalent to a morphism.
 }
 
+// IsMorphism returns whether this Path is a morphism.
 func (p *Path) IsMorphism() bool { return p.qs == nil }
 
+// StartMorphism creates a new Path with no underlying QuadStore.
 func StartMorphism(nodes ...string) *Path {
 	return StartPath(nil, nodes...)
 }
 
+// StartPath creates a new Path from a set of nodes and an underlying QuadStore.
 func StartPath(qs graph.QuadStore, nodes ...string) *Path {
 	return &Path{
 		stack: []morphism{
@@ -55,12 +60,14 @@ func PathFromIterator(qs graph.QuadStore, it graph.Iterator) *Path {
 	}
 }
 
+// NewPath creates a new, empty Path.
 func NewPath(qs graph.QuadStore) *Path {
 	return &Path{
 		qs: qs,
 	}
 }
 
+// Reverse returns a new Path that is the reverse of the current one.
 func (p *Path) Reverse() *Path {
 	newPath := NewPath(p.qs)
 	for i := len(p.stack) - 1; i >= 0; i-- {
@@ -79,25 +86,54 @@ func (p *Path) Tag(tags ...string) *Path {
 	return p
 }
 
+// Out updates this Path to represent the nodes that are adjacent to the
+// current nodes, via the given outbound predicate.
+//
+// For example:
+//  // Returns the list of nodes that "A" follows.
+//  //
+//  // Will return []string{"B"} if there is a predicate (edge) from "A"
+//  // to "B" labelled "follows".
+//  StartPath(qs, "A").Out("follows")
 func (p *Path) Out(via ...interface{}) *Path {
 	p.stack = append(p.stack, outMorphism(via...))
 	return p
 }
+
+// In updates this Path to represent the nodes that are adjacent to the
+// current nodes, via the given inbound predicate.
+//
+// For example:
+//  // Return the list of nodes that follow "B".
+//  //
+//  // Will return []string{"A", "C", "D"} if there are the appropriate
+//  // edges from those nodes to "B" labelled "follows".
+//  StartPath(qs, "B").In("follows")
 func (p *Path) In(via ...interface{}) *Path {
 	p.stack = append(p.stack, inMorphism(via...))
 	return p
 }
 
+// And updates the current Path to represent the nodes that match both the
+// current Path so far, and the given Path.
 func (p *Path) And(path *Path) *Path {
 	p.stack = append(p.stack, andMorphism(path))
 	return p
 }
 
+// And updates the current Path to represent the nodes that match either the
+// current Path so far, or the given Path.
 func (p *Path) Or(path *Path) *Path {
 	p.stack = append(p.stack, orMorphism(path))
 	return p
 }
 
+// Except updates the current Path to represent the all of the current nodes
+// except those in the supplied Path.
+//
+// For example:
+//  // Will return []string{"B"}
+//  StartPath(qs, "A", "B").Except(StartPath(qs, "A"))
 func (p *Path) Except(path *Path) *Path {
 	p.stack = append(p.stack, exceptMorphism(path))
 	return p
@@ -113,6 +149,10 @@ func (p *Path) FollowReverse(path *Path) *Path {
 	return p
 }
 
+// BuildIterator returns an iterator from this given Path.  Note that you must
+// call this with a full path (not a morphism), since a morphism does not have
+// the ability to fetch the underlying quads.  This function will panic if
+// called with a morphism (i.e. if p.IsMorphism() is true).
 func (p *Path) BuildIterator() graph.Iterator {
 	if p.IsMorphism() {
 		panic("Building an iterator from a morphism. Bind a QuadStore with BuildIteratorOn(qs)")
@@ -120,10 +160,15 @@ func (p *Path) BuildIterator() graph.Iterator {
 	return p.BuildIteratorOn(p.qs)
 }
 
+// BuildIteratorOn will return an iterator for this path on the given QuadStore.
 func (p *Path) BuildIteratorOn(qs graph.QuadStore) graph.Iterator {
 	return p.Morphism()(qs, qs.NodesAllIterator())
 }
 
+// Morphism returns the morphism of this path.  The returned value is a
+// function that, when given a QuadStore and an existing Iterator, will
+// return a new Iterator that yields the subset of values from the existing
+// iterator matched by the current Path.
 func (p *Path) Morphism() graph.ApplyMorphism {
 	return func(qs graph.QuadStore, it graph.Iterator) graph.Iterator {
 		i := it.Clone()