test: [a-c]: add introductory comments to tests

Very few of the compiler regression tests include a comment
saying waht they do. Many are obvious, some are anything but.
I've started with a-c in the top directory. More will follow once
we agree on the approach, correctness, and thoroughness here.
zerodivide.go sneaked in too.

R=rsc, r
CC=golang-dev
https://golang.org/cl/5656100

test/235.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.
 
+// Solve the 2,3,5 problem (print all numbers with 2, 3, or 5 as factor) using channels.
+// Test the solution, silently.
+
 package main
 
 type T chan uint64

test/alias.go

@@ -4,10 +4,11 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-package main
-
 // Test that error messages say what the source file says
 // (uint8 vs byte, int32 vs. rune).
+// Does not compile.
+
+package main
 
 import (
  "fmt"

test/alias1.go

@@ -4,11 +4,11 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-package main
-
 // Test that dynamic interface checks treat byte=uint8
 // and rune=int or rune=int32.
 
+package main
+
 func main() {
  var x interface{}
 

test/append.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.
 
-// Semi-exhaustive test for append()
+// Semi-exhaustive test for the append predeclared function.
 
 package main
 

test/args.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 os.Args.
+
 package main
 
 import "os"

test/assign.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 simple assignment errors are caught by the compiler.
+// Does not compile.
+
 package main
 
 import "sync"

test/assign1.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 assignment rules are enforced by the compiler.
+// Does not compile.
+
 package main
 
 type (

test/bigalg.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 the internal "algorithms" for objects larger than a word: hashing, equality etc.
+
 package main
 
 type T struct {

test/bigmap.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 behavior of maps with large elements.
+
 package main
 
 func seq(x, y int) [1000]byte {

test/blank.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 behavior of the blank identifier (_).
+
 package main
 
 import _ "fmt"

test/blank1.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 incorrect uses of the blank identifer are caught.
+// Does not compile.
+
 package _ // ERROR "invalid package name _"
 
 func main() {

test/chancap.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 the cap predeclared function applied to channels.
+
 package main
 
 func main() {

test/char_lit.go

@@ -1,9 +1,11 @@
-// $G $F.go && $L $F.$A &&./$A.out
+// run
 
 // 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 character literal syntax.
+
 package main
 
 import "os"

test/char_lit1.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 character literals are detected.
+// Does not compile.
+
 package main
 
 const (

test/closure.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 the behavior of closures.
+
 package main
 
 import "runtime"

test/cmp.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 equality and inequality operations.
+
 package main
 
 import "unsafe"

test/cmp6.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 incorrect comparisons are detected.
+// Does not compile.
+
 package main
 
 func use(bool) {}

test/cmplx.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 incorrect invocations of the complex predeclared function are detected.
+// Does not compile.
+
 package main
 
 var (

test/complit.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 composite literals.
+
 package main
 
 type T struct {

test/complit1.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 composite literals are detected.
+// Does not compile.
+
 package main
 
 var m map[int][3]int

test/compos.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 returning &T{} from a function causes an allocation.
+
 package main
 
 type T struct {

test/const.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 simple boolean and numeric constants.
+
 package main
 
 const (

test/const1.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 overflow is detected when using numeric constants.
+// Does not compile.
+
 package main
 
 type I interface{}

test/const2.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 large integer constant expressions cause overflow.
+// Does not compile.
+
 package main
 
 const (

test/const3.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 typed integer constants.
+
 package main
 
 import "fmt"

test/convert.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 types of constant expressions, using reflect.
+
 package main
 
 import "reflect"

test/convert1.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 conversions involving strings are detected.
+// Does not compile.
+
 package main
 
 type Tbyte []byte

test/convert3.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 allowed and disallowed conversions.
+// Does not compile.
+
 package main
 
 // everything here is legal except the ERROR line

test/convlit.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.
 
+// Verify that illegal assignments with both explicit and implicit conversions of literals are detected.
+// Does not compile.
+
 package main
 
-// explicit conversion of constants is work in progress.
-// the ERRORs in this block are debatable, but they're what
-// the language spec says for now.
+// explicit conversion of constants
 var x1 = string(1)
 var x2 string = string(1)
 var x3 = int(1.5) // ERROR "convert|truncate"

test/convlit1.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 composite literals are detected.
+// Does not compile.
+
 package main
 
 var a = []int { "a" }; // ERROR "conver|incompatible|cannot"

test/copy.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.
 
-// Semi-exhaustive test for copy()
+// Semi-exhaustive test for the copy predeclared function.
 
 package main
 

test/zerodivide.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 zero division causes a panic.
+
 package main
 
 import (