From ccd7bd017e424780c2010e8660eb7b6af74e29df Mon Sep 17 00:00:00 2001
From: Nick Fagerlund <nick.fagerlund@gmail.com>
Date: Thu, 6 Oct 2022 15:10:33 -0700
Subject: [PATCH] Clarify some comments in internal/dag

When reading this code to check Terraform's graph sorting behavior, I got very
confused about the direction of traversal for several methods. Although some of
these methods would also probably benefit from renames, this commit only updates
their doc comments to use the same directional terminology that we use in the
`Edge` interface (source/target).
---
 internal/dag/dag.go   | 14 ++++++++------
 internal/dag/graph.go | 19 ++++++++++---------
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/internal/dag/dag.go b/internal/dag/dag.go
index f5268e76f0..362c847f3d 100644
--- a/internal/dag/dag.go
+++ b/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)
 }
diff --git a/internal/dag/graph.go b/internal/dag/graph.go
index b609558d41..ab1ae37566 100644
--- a/internal/dag/graph.go
+++ b/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)]