cmd/dist: add doc comments to some functions

I keep having to reconstruct how dist test's command system works.
This CL documents the main functions to help with this.

Change-Id: Ic1102496d3c7f356e73f3fa2ea76498251f525d4
Reviewed-on: https://go-review.googlesource.com/c/go/+/448799
Run-TryBot: Austin Clements <austin@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>

1 files changed, 9 insertions, 0 deletions

diff --git a/src/cmd/dist/test.go b/src/cmd/dist/test.go
index 46ab0c7bcb..b3c282a869 100644
--- a/src/cmd/dist/test.go
+++ b/src/cmd/dist/test.go
@@ -921,6 +921,9 @@ func (t *tester) registerSeqTest(name, dirBanner string, cmdline ...interface{})
 	t.registerTest1(true, name, dirBanner, cmdline...)
 }
 
+// bgDirCmd constructs a Cmd intended to be run in the background as
+// part of the worklist. The worklist runner will buffer its output
+// and replay it sequentially. The command will be run in dir.
 func (t *tester) bgDirCmd(dir, bin string, args ...string) *exec.Cmd {
 	cmd := exec.Command(bin, args...)
 	if filepath.IsAbs(dir) {
@@ -931,6 +934,9 @@ func (t *tester) bgDirCmd(dir, bin string, args ...string) *exec.Cmd {
 	return cmd
 }
 
+// dirCmd constructs a Cmd intended to be run in the foreground.
+// The command will be run in dir, and Stdout and Stderr will go to os.Stdout
+// and os.Stderr.
 func (t *tester) dirCmd(dir string, cmdline ...interface{}) *exec.Cmd {
 	bin, args := flattenCmdline(cmdline)
 	cmd := t.bgDirCmd(dir, bin, args...)
@@ -990,6 +996,9 @@ func flattenCmdline(cmdline []interface{}) (bin string, args []string) {
 	return bin, list[1:]
 }
 
+// addCmd adds a command to the worklist. Commands can be run in
+// parallel, but their output will be buffered and replayed in the
+// order they were added to worklist.
 func (t *tester) addCmd(dt *distTest, dir string, cmdline ...interface{}) *exec.Cmd {
 	bin, args := flattenCmdline(cmdline)
 	w := &work{