test: explanatory comments [c-g]*

R=golang-dev, bradfitz
CC=golang-dev
http://codereview.appspot.com/5656103

33 files changed, 76 insertions, 12 deletions

diff --git a/test/ddd.go b/test/ddd.go
index aa799be27..f35836331 100644
--- a/test/ddd.go
+++ b/test/ddd.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test variadic functions and calls (dot-dot-dot).
+
 package main
 
 func sum(args ...int) int {
diff --git a/test/ddd1.go b/test/ddd1.go
index 3eab78a56..1e070093c 100644
--- a/test/ddd1.go
+++ b/test/ddd1.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Verify that illegal uses of ... are detected.
+// Does not compile.
+
 package main
 
 import "unsafe"
diff --git a/test/ddd2.go b/test/ddd2.go
index a06af0c06..2edae36b1 100644
--- a/test/ddd2.go
+++ b/test/ddd2.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This file is compiled and then imported by ddd3.go.
+
 package ddd
 
 func Sum(args ...int) int {
diff --git a/test/ddd3.go b/test/ddd3.go
index 5d5ebdf0f..82fce3149 100644
--- a/test/ddd3.go
+++ b/test/ddd3.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test that variadic functions work across package boundaries.
+
 package main
 
 import "./ddd2"
diff --git a/test/decl.go b/test/decl.go
index 4a7d86794..6f84245f1 100644
--- a/test/decl.go
+++ b/test/decl.go
@@ -4,7 +4,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Correct short declarations and redeclarations.
+// Test correct short declarations and redeclarations.
 
 package main
 
diff --git a/test/declbad.go b/test/declbad.go
index 962a61c0f..32d68e7ea 100644
--- a/test/declbad.go
+++ b/test/declbad.go
@@ -4,7 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Incorrect short declarations and redeclarations.
+// Test that incorrect short declarations and redeclarations are detected.
+// Does not compile.
 
 package main
 
diff --git a/test/defer.go b/test/defer.go
index 30276649b..2f67d3560 100644
--- a/test/defer.go
+++ b/test/defer.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test defer.
+
 package main
 
 import "fmt"
diff --git a/test/deferprint.go b/test/deferprint.go
index 0e0c61821..eab7ed465 100644
--- a/test/deferprint.go
+++ b/test/deferprint.go
@@ -4,11 +4,14 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test that we can defer the predeclared functions print and println.
+
 package main
 
 func main() {
 	defer println(42, true, false, true, 1.5, "world", (chan int)(nil), []int(nil), (map[string]int)(nil), (func())(nil), byte(255))
 	defer println(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20)
-//	defer panic("dead")
+	// Disabled so the test doesn't crash but left here for reference.
+	// defer panic("dead")
 	defer print("printing: ")
 }
diff --git a/test/divide.go b/test/divide.go
index 75597f515..c91a33e9d 100644
--- a/test/divide.go
+++ b/test/divide.go
@@ -4,7 +4,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// divide corner cases
+// Test divide corner cases.
 
 package main
 
diff --git a/test/empty.go b/test/empty.go
index 7f2bf1a04..92a79a4e0 100644
--- a/test/empty.go
+++ b/test/empty.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test that top-level parenthesized declarations can be empty.
+// Compiles but does not run.
+
 package P
 
 import ( )
diff --git a/test/env.go b/test/env.go
index 721df55c0..4dcf4443a 100644
--- a/test/env.go
+++ b/test/env.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test that the Go environment variables are present and accessible through
+// package os and package runtime.
+
 package main
 
 import (
diff --git a/test/eof.go b/test/eof.go
index 71a9f8515..06c779046 100644
--- a/test/eof.go
+++ b/test/eof.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test a source file does not need a final newline.
+// Compiles but does not run.
+
 // No newline at the end of this file.
 
 package main
\ No newline at end of file
diff --git a/test/eof1.go b/test/eof1.go
index af6b4c52f..2105b8908 100644
--- a/test/eof1.go
+++ b/test/eof1.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test that a comment ending a source file does not need a final newline.
+// Compiles but does not run.
+
 package eof1
 
 // No newline at the end of this comment.
\ No newline at end of file
diff --git a/test/escape.go b/test/escape.go
index 6c0cdc463..e487bb895 100644
--- a/test/escape.go
+++ b/test/escape.go
@@ -6,8 +6,8 @@
 
 package main
 
-// check for correct heap-moving of escaped variables.
-// it is hard to check for the allocations, but it is easy
+// Test for correct heap-moving of escaped variables.
+// It is hard to check for the allocations, but it is easy
 // to check that if you call the function twice at the
 // same stack level, the pointers returned should be
 // different.
diff --git a/test/escape2.go b/test/escape2.go
index 73b2a7e58..dde96bcc1 100644
--- a/test/escape2.go
+++ b/test/escape2.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test, using compiler diagnostic flags, that the escape analysis is working.
+// Compiles but does not run.
+
 package foo
 
 import (
diff --git a/test/escape3.go b/test/escape3.go
index 0612ae2dd..4c1989151 100644
--- a/test/escape3.go
+++ b/test/escape3.go
@@ -4,7 +4,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Test run-time behavior of escape analysis-related optimizations.
+// Test the run-time behavior of escape analysis-related optimizations.
 
 package main
 
diff --git a/test/float_lit.go b/test/float_lit.go
index 3189cac22..2912c3749 100644
--- a/test/float_lit.go
+++ b/test/float_lit.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test floating-point literal syntax.
+
 package main
 
 var bad bool
diff --git a/test/floatcmp.go b/test/floatcmp.go
index 2a5bd75df..f9f59a937 100644
--- a/test/floatcmp.go
+++ b/test/floatcmp.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test floating-point comparison involving NaN.
+
 package main
 
 import "math"
diff --git a/test/for.go b/test/for.go
index a21213ff3..8a5009065 100644
--- a/test/for.go
+++ b/test/for.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test for loops.
+
 package main
 
 func assertequal(is, shouldbe int, msg string) {
diff --git a/test/func.go b/test/func.go
index 15839c05f..246cb56fd 100644
--- a/test/func.go
+++ b/test/func.go
@@ -4,6 +4,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test simple functions.
 
 package main
 
diff --git a/test/func1.go b/test/func1.go
index d5adea71e..c89f7ff2e 100644
--- a/test/func1.go
+++ b/test/func1.go
@@ -4,11 +4,12 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// does not compile and should not compile
+// Test that result parameters are in the same scope as regular parameters.
+// Does not compile.
 
 package main
 
-func f1(a int) (int, float32) { // BUG (not caught by compiler): multiple return values must have names
+func f1(a int) (int, float32) {
 	return 7, 7.0
 }
 
diff --git a/test/func2.go b/test/func2.go
index 87e78194e..b5966a91f 100644
--- a/test/func2.go
+++ b/test/func2.go
@@ -1,9 +1,12 @@
-// $G $F.go || echo BUG: should compile
+// compile
 
 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test function signatures.
+// Compiled but not run.
+
 package main
 
 type t1 int
diff --git a/test/func3.go b/test/func3.go
index 587b7c4a1..6be3bf018 100644
--- a/test/func3.go
+++ b/test/func3.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Verify that illegal function signatures are detected.
+// Does not compile.
+
 package main
 
 type t1 int
diff --git a/test/func4.go b/test/func4.go
index c53e7a23a..85f1e4b81 100644
--- a/test/func4.go
+++ b/test/func4.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Verify that it is illegal to take the address of a function.
+// Does not compile.
+
 package main
 
 var notmain func()
diff --git a/test/func5.go b/test/func5.go
index 68ab7a54b..2e058be7e 100644
--- a/test/func5.go
+++ b/test/func5.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test functions and goroutines.
+
 package main
 
 func caller(f func(int, int) int, a, b int, c chan int) {
diff --git a/test/func6.go b/test/func6.go
index 39c15329e..456cb49f0 100644
--- a/test/func6.go
+++ b/test/func6.go
@@ -1,9 +1,11 @@
-// compile
+// run
 
 // Copyright 2011 The Go Authors.  All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test closures in if conditions.
+
 package main
 
 func main() {
diff --git a/test/func7.go b/test/func7.go
index 015b881fb..6f6766f29 100644
--- a/test/func7.go
+++ b/test/func7.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test evaluation order in if condition.
+
 package main
 
 var calledf = false
diff --git a/test/func8.go b/test/func8.go
index a1ea9b7e4..7defe265b 100644
--- a/test/func8.go
+++ b/test/func8.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test evaluation order.
+
 package main
 
 var calledf int
diff --git a/test/gc.go b/test/gc.go
index e610d2bde..6688f9fbd 100644
--- a/test/gc.go
+++ b/test/gc.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Simple test of the garbage collector.
+
 package main
 
 import "runtime"
diff --git a/test/gc1.go b/test/gc1.go
index 190b29b00..6049ea14e 100644
--- a/test/gc1.go
+++ b/test/gc1.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// A simple test of the garbage collector.
+
 package main
 
 func main() {
diff --git a/test/gc2.go b/test/gc2.go
index 739183e59..de52a4fbf 100644
--- a/test/gc2.go
+++ b/test/gc2.go
@@ -4,7 +4,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Check that buffered channels are garbage collected properly.
+// Test that buffered channels are garbage collected properly.
 // An interesting case because they have finalizers and used to
 // have self loops that kept them from being collected.
 // (Cyclic data with finalizers is never finalized, nor collected.)
diff --git a/test/goprint.go b/test/goprint.go
index 53ed055a0..3fe08f307 100644
--- a/test/goprint.go
+++ b/test/goprint.go
@@ -4,6 +4,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Test that println can be the target of a go statement.
+
 package main
 
 import "time"
diff --git a/test/goto.go b/test/goto.go
index 11417f86b..ca477b3d0 100644
--- a/test/goto.go
+++ b/test/goto.go
@@ -4,6 +4,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Verify goto semantics.
+// Does not compile.
+//
 // Each test is in a separate function just so that if the
 // compiler stops processing after one error, we don't
 // lose other ones.