task graph: sprinkle comments and fix typos

Author: petr-muller

pkg/payload/task_graph.go

@@ -128,10 +128,15 @@ func FlattenByNumberAndComponent(tasks []*Task) [][]*TaskNode {
 	return [][]*TaskNode{groups}
 }
 
+// TaskNode represents a node in a TaskGraph. The node assumes the graph is indexable and nodes are retrievable by index,
+// and In/Out are indices of other nodes connected to this one by incoming/outgoing edges, respectively.
 type TaskNode struct {
-	In    []int
+	// In is a list of node indices from which there is an edge to this node (=prerequisites)
+	In []int
+	// Tasks to be executed when this node is visited
 	Tasks []*Task
-	Out   []int
+	// Out is a list of node indices to which there is an edge from this node (=dependents).
+	Out []int
 }
 
 func (n TaskNode) String() string {
@@ -262,7 +267,7 @@ func (g *TaskGraph) Split(onFn func(task *Task) bool) {
 }
 
 // BreakFunc returns the input tasks in order of dependencies with
-// explicit parallelizm allowed per task in an array of task nodes.
+// explicit parallelism allowed per task in an array of task nodes.
 type BreakFunc func([]*Task) [][]*TaskNode
 
 // ShiftOrder rotates each TaskNode by step*len/stride when stride > len,
@@ -424,8 +429,8 @@ type taskStatus struct {
 }
 
 // RunGraph executes the provided graph in order and in parallel up to maxParallelism. It will not start
-// a new TaskNode until all of the prerequisites have completed. If fn returns an error, no dependencies
-// of that node will be executed, but other indepedent edges will continue executing.
+// a new TaskNode until all its prerequisites have completed. If fn returns an error, no dependencies
+// of that node will be executed, but other independent edges will continue executing.
 func RunGraph(ctx context.Context, graph *TaskGraph, maxParallelism int, fn func(ctx context.Context, tasks []*Task) error) []error {
 	submitted := make([]bool, len(graph.Nodes))
 	results := make([]*taskStatus, len(graph.Nodes))
@@ -452,7 +457,7 @@ func RunGraph(ctx context.Context, graph *TaskGraph, maxParallelism int, fn func
 		return -1
 	}
 
-	// Tasks go out to the workers via workCh, and results come brack
+	// Tasks go out to the workers via workCh, and results come back
 	// from the workers via resultCh.
 	workCh := make(chan runTasks, maxParallelism)
 	defer close(workCh)

pkg/payload/task_graph_test.go

@@ -743,6 +743,8 @@ func TestRunGraph(t *testing.T) {
 		{
 			name: "nodes executed after dependencies",
 			nodes: []*TaskNode{
+				// In: prerequisites (by index)
+				// Out: dependents (by index)
 				{Tasks: tasks("c"), In: []int{3}},
 				{Tasks: tasks("d", "e"), In: []int{3}},
 				{Tasks: tasks("f"), In: []int{3}, Out: []int{4}},
@@ -773,6 +775,8 @@ func TestRunGraph(t *testing.T) {
 		{
 			name: "task error interrupts node processing",
 			nodes: []*TaskNode{
+				// In: prerequisites (by index)
+				// Out: dependents (by index)
 				{Tasks: tasks("c"), In: []int{2}},
 				{Tasks: tasks("d"), In: []int{2}, Out: []int{3}},
 				{Tasks: tasks("a", "b"), Out: []int{0, 1}},
@@ -799,6 +803,8 @@ func TestRunGraph(t *testing.T) {
 		{
 			name: "mid-task cancellation error interrupts node processing",
 			nodes: []*TaskNode{
+				// In: prerequisites (by index)
+				// Out: dependents (by index)
 				{Tasks: tasks("c"), In: []int{2}},
 				{Tasks: tasks("d"), In: []int{2}, Out: []int{3}},
 				{Tasks: tasks("a", "b"), Out: []int{0, 1}},
@@ -853,6 +859,8 @@ func TestRunGraph(t *testing.T) {
 		{
 			name: "task errors in parallel nodes both reported",
 			nodes: []*TaskNode{
+				// In: prerequisites (by index)
+				// Out: dependents (by index)
 				{Tasks: tasks("a"), Out: []int{1}},
 				{Tasks: tasks("b"), In: []int{0}, Out: []int{2, 4, 8}},
 				{Tasks: tasks("c1"), In: []int{1}, Out: []int{3}},
@@ -878,8 +886,10 @@ func TestRunGraph(t *testing.T) {
 			wantErrs: []string{"error - c1", "error - f"},
 		},
 		{
-			name: "cancelation without task errors is reported",
+			name: "cancellation without task errors is reported",
 			nodes: []*TaskNode{
+				// In: prerequisites (by index)
+				// Out: dependents (by index)
 				{Tasks: tasks("a"), Out: []int{1}},
 				{Tasks: tasks("b"), In: []int{0}},
 			},