test: explanatory comments [c-g]*

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5656103

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 {

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"

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 {

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"

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
 

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
 

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"

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: ")
 }

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
 

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

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 (

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

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

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.

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 (

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
 

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

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"

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

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
 

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
 }
 

test/func2.go

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

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

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

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

test/func6.go

-// 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() {

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

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

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"

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() {

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

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"

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.