Clarify interface regarding ready state and add relevant test (#18)

* Clarify interface and add relevant test

* Address review comments

dg_test.go

@@ -182,6 +182,24 @@ func TestDirectedGraph_OneAndDependencyConnectDependency(t *testing.T) {
 		})
 }
 
+func TestDirectedGraph_ResolvingSingleNode(t *testing.T) {
+	// This test makes sure that only dependent nodes get marked as ready.
+	// Since there are no dependencies between nodes here, marking nodes as resolved
+	// should not cause any nodes to be placed on the ready list.
+	d := dgraph.New[string]()
+	resolvedNode, err := d.AddNode("resolved-node", "resolved-node")
+	assert.NoError(t, err)
+	unresolvableNode, err := d.AddNode("unresolvable-node", "unresolvable-node")
+	assert.NoError(t, err)
+	// Purposefully skip PushStartingNodes. This tests the behavior of a single node.
+	// Calling PushStartingNodes would add both nodes to the list.
+	assert.Equals(t, d.HasReadyNodes(), false)
+	assert.NoError(t, resolvedNode.ResolveNode(dgraph.Resolved))
+	assert.Equals(t, d.HasReadyNodes(), false)
+	assert.NoError(t, unresolvableNode.ResolveNode(dgraph.Unresolvable))
+	assert.Equals(t, d.HasReadyNodes(), false)
+}
+
 func TestDirectedGraph_TwoAndDependencies(t *testing.T) {
 	d := dgraph.New[string]()
 	dependentNode, err := d.AddNode("dependent-node", "Dependent Node")

interfaces.go

@@ -44,15 +44,16 @@ type DirectedGraph[NodeType any] interface {
 	Clone() DirectedGraph[NodeType]
 	// HasCycles performs cycle detection and returns true if the DirectedGraph has cycles.
 	HasCycles() bool
-	// PopReadyNodes returns of a list of all nodes that have finalized their status, whether
-	// resolved or unresolvable, and clears the list.
-	// A node becomes ready to process when all of its AND dependencies and at least one of
+	// PopReadyNodes returns of a list of all nodes that have no outstanding required dependencies,
+	// and are therefore ready, and clears the list.
+	// A node becomes ready when all of its AND dependencies and at least one of
 	// its OR dependencies are resolved.
+	// Note that the resolution state of a node is independent of its readiness and that the
+	// status varies depending on the behavior of the calling code.
 	PopReadyNodes() map[string]ResolutionStatus
 	// HasReadyNodes checks to see if there are any ready nodes without clearing them.
 	HasReadyNodes() bool
-	// PushStartingNodes searches for the initial ready nodes without dependencies and saves them.
-	// The nodes can then be retrieved with a call to `PopReadyNodes()`.
+	// PushStartingNodes initializes the list which is retrieved using `PopReadyNodes()`.
 	// Recommended to be called only once following construction of the DAG.
 	PushStartingNodes() error