From: Austin Clements <austin@google.com>
Date: Thu, 13 Oct 2022 14:54:11 +0000 (-0400)
Subject: cmd/dist: add doc comments to some functions
X-Git-Tag: go1.20rc1~221
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=9c402305179e4d59bcbefe01629d38fc26808c43;p=gostls13.git

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>
---

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{