Merge pull request #31959 from hashicorp/nf/oct22-updown-comments

Clarify some comments in internal/dag

internal/dag/dag.go

@@ -179,16 +179,18 @@ type vertexAtDepth struct {
 	Depth  int
 }
 
-// TopologicalOrder returns a topological sort of the given graph. The nodes
-// are not sorted, and any valid order may be returned. This function will
-// panic if it encounters a cycle.
+// TopologicalOrder returns a topological sort of the given graph, with source
+// vertices ordered before the targets of their edges. The nodes are not sorted,
+// and any valid order may be returned. This function will panic if it
+// encounters a cycle.
 func (g *AcyclicGraph) TopologicalOrder() []Vertex {
 	return g.topoOrder(upOrder)
 }
 
-// ReverseTopologicalOrder returns a topological sort of the given graph,
-// following each edge in reverse. The nodes are not sorted, and any valid
-// order may be returned. This function will panic if it encounters a cycle.
+// ReverseTopologicalOrder returns a topological sort of the given graph, with
+// target vertices ordered before the sources of their edges. The nodes are not
+// sorted, and any valid order may be returned. This function will panic if it
+// encounters a cycle.
 func (g *AcyclicGraph) ReverseTopologicalOrder() []Vertex {
 	return g.topoOrder(downOrder)
 }

internal/dag/graph.go

@@ -166,28 +166,29 @@ func (g *Graph) RemoveEdge(edge Edge) {
 	}
 }
 
-// UpEdges returns the vertices connected to the outward edges from the source
-// Vertex v.
+// UpEdges returns the vertices that are *sources* of edges that target the
+// destination Vertex v.
 func (g *Graph) UpEdges(v Vertex) Set {
 	return g.upEdgesNoCopy(v).Copy()
 }
 
-// DownEdges returns the vertices connected from the inward edges to Vertex v.
+// DownEdges returns the vertices that are *targets* of edges that originate
+// from the source Vertex v.
 func (g *Graph) DownEdges(v Vertex) Set {
 	return g.downEdgesNoCopy(v).Copy()
 }
 
-// downEdgesNoCopy returns the outward edges from the source Vertex v as a Set.
-// This Set is the same as used internally bu the Graph to prevent a copy, and
-// must not be modified by the caller.
+// downEdgesNoCopy returns the vertices targeted by edges from the source Vertex
+// v as a Set. This Set is the same as used internally by the Graph to prevent a
+// copy, and must not be modified by the caller.
 func (g *Graph) downEdgesNoCopy(v Vertex) Set {
 	g.init()
 	return g.downEdges[hashcode(v)]
 }
 
-// upEdgesNoCopy returns the inward edges to the destination Vertex v as a Set.
-// This Set is the same as used internally bu the Graph to prevent a copy, and
-// must not be modified by the caller.
+// upEdgesNoCopy returns the vertices that are sources of edges targeting the
+// destination Vertex v as a Set. This Set is the same as used internally by the
+// Graph to prevent a copy, and must not be modified by the caller.
 func (g *Graph) upEdgesNoCopy(v Vertex) Set {
 	g.init()
 	return g.upEdges[hashcode(v)]