test: add comments for all test actions

Every action has a short annotation.
The errorCheck function has a comment adapted from errchk script.

Removed redundant assigments to tmpDir.

Change-Id: Ifdd1284de046a0ce2aad26bd8da8a8e6a7707a8e
Reviewed-on: https://go-review.googlesource.com/115856
Run-TryBot: Yury Smolsky <yury@smolsky.by>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

test/run.go

@@ -616,6 +616,8 @@ func (t *test) run() {
 		t.err = fmt.Errorf("unimplemented action %q", action)
 
 	case "asmcheck":
+		// Compile Go file and match the generated assembly
+		// against a set of regexps in comments.
 		ops := t.wantedAsmOpcodes(long)
 		for _, env := range ops.Envs() {
 			cmdline := []string{"build", "-gcflags", "-S"}
@@ -640,6 +642,9 @@ func (t *test) run() {
 		return
 
 	case "errorcheck":
+		// Compile Go file.
+		// Fail if wantError is true and compilation was successful and vice versa.
+		// Match errors produced by gc against errors in comments.
 		// TODO(gri) remove need for -C (disable printing of columns in error messages)
 		cmdline := []string{goTool(), "tool", "compile", "-C", "-e", "-o", "a.o"}
 		// No need to add -dynlink even if linkshared if we're just checking for errors...
@@ -664,10 +669,11 @@ func (t *test) run() {
 		return
 
 	case "compile":
+		// Compile Go file.
 		_, t.err = compileFile(runcmd, long, flags)
 
 	case "compiledir":
-		// Compile all files in the directory in lexicographic order.
+		// Compile all files in the directory as packages in lexicographic order.
 		longdir := filepath.Join(cwd, t.goDirName())
 		pkgs, err := goDirPackages(longdir, singlefilepkgs)
 		if err != nil {
@@ -682,8 +688,9 @@ func (t *test) run() {
 		}
 
 	case "errorcheckdir", "errorcheckandrundir":
-		// errorcheck all files in lexicographic order
+		// Compile and errorCheck all files in the directory as packages in lexicographic order.
-		// useful for finding importing errors
+		// If errorcheckdir and wantError, compilation of the last package must fail.
+		// If errorcheckandrundir and wantError, compilation of the package prior the last must fail.
 		longdir := filepath.Join(cwd, t.goDirName())
 		pkgs, err := goDirPackages(longdir, singlefilepkgs)
 		if err != nil {
@@ -725,8 +732,10 @@ func (t *test) run() {
 		fallthrough
 
 	case "rundir":
-		// Compile all files in the directory in lexicographic order.
+		// Compile all files in the directory as packages in lexicographic order.
-		// then link as if the last file is the main package and run it
+		// In case of errorcheckandrundir, ignore failed compilation of the package before the last.
+		// Link as if the last file is the main package, run it.
+		// Verify the expected output.
 		longdir := filepath.Join(cwd, t.goDirName())
 		pkgs, err := goDirPackages(longdir, singlefilepkgs)
 		if err != nil {
@@ -763,6 +772,7 @@ func (t *test) run() {
 		}
 
 	case "build":
+		// Build Go file.
 		_, err := runcmd(goTool(), "build", goGcflags(), "-o", "a.exe", long)
 		if err != nil {
 			t.err = err
@@ -770,7 +780,7 @@ func (t *test) run() {
 
 	case "builddir", "buildrundir":
 		// Build an executable from all the .go and .s files in a subdirectory.
-		useTmp = true
+		// Run it and verify its output in the buildrundir case.
 		longdir := filepath.Join(cwd, t.goDirName())
 		files, dirErr := ioutil.ReadDir(longdir)
 		if dirErr != nil {
@@ -839,9 +849,10 @@ func (t *test) run() {
 			}
 		}
 
-	case "buildrun": // build binary, then run binary, instead of go run. Useful for timeout tests where failure mode is infinite loop.
+	case "buildrun":
+		// Build an executable from Go file, then run it, verify its output.
+		// Useful for timeout tests where failure mode is infinite loop.
 		// TODO: not supported on NaCl
-		useTmp = true
 		cmd := []string{goTool(), "build", goGcflags(), "-o", "a.exe"}
 		if *linkshared {
 			cmd = append(cmd, "-linkshared")
@@ -866,6 +877,9 @@ func (t *test) run() {
 		}
 
 	case "run":
+		// Run Go file if no special go command flags are provided;
+		// otherwise build an executable and run it.
+		// Verify the output.
 		useTmp = false
 		var out []byte
 		var err error
@@ -908,6 +922,8 @@ func (t *test) run() {
 		}
 
 	case "runoutput":
+		// Run Go file and write its output into temporary Go file.
+		// Run generated Go file and verify its output.
 		rungatec <- true
 		defer func() {
 			<-rungatec
@@ -943,6 +959,8 @@ func (t *test) run() {
 		}
 
 	case "errorcheckoutput":
+		// Run Go file and write its output into temporary Go file.
+		// Compile and errorCheck generated Go file.
 		useTmp = false
 		cmd := []string{goTool(), "run", goGcflags()}
 		if *linkshared {
@@ -1038,6 +1056,17 @@ func splitOutput(out string, wantAuto bool) []string {
 	return res
 }
 
+// errorCheck matches errors in outStr against comments in source files.
+// For each line of the source files which should generate an error,
+// there should be a comment of the form // ERROR "regexp".
+// If outStr has an error for a line which has no such comment,
+// this function will report an error.
+// Likewise if outStr does not have an error for a line which has a comment,
+// or if the error message does not match the <regexp>.
+// The <regexp> syntax is Perl but its best to stick to egrep.
+//
+// Sources files are supplied as fullshort slice.
+// It consists of pairs: full path to source file and it's base name.
 func (t *test) errorCheck(outStr string, wantAuto bool, fullshort ...string) (err error) {
 	defer func() {
 		if *verbose && err != nil {