document testing and incidentally gotest

R=rsc
DELTA=25  (25 added, 0 deleted, 0 changed)
OCL=25798
CL=25802

diff --git a/src/lib/testing.go b/src/lib/testing.go
index d4abdfb5e4041b22864eb82602bbd45789fdcbfd..4f43ddff1e42883c4ff031f0d8016c1b6bae47dc 100644 (file)
--- a/src/lib/testing.go
+++ b/src/lib/testing.go
@@ -2,6 +2,13 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// The testing package provides support for automated testing of Go packages.
+// It is intended to be used in concert with the ``gotest'' utility, which automates
+// execution of any function of the form
+//     func TestXxx(*testing.T)
+// where Xxx can by any alphanumeric string (but the first letter must not be in
+// [a-z]) and serves to identify the test routine.
+// These TestXxx routines should be declared within the package they are testing.
 package testing
 
 import (
@@ -9,6 +16,7 @@ import (
        "flag";
 )
 
+// Report as tests are run; default is silent for success.
 var chatty = flag.Bool("chatty", false, "chatty")
 
 // Insert tabs after newlines - but not the last one
@@ -21,26 +29,35 @@ func tabify(s string) string {
        return s
 }
 
+// T is a type passed to Test functions to manage test state and support formatted test logs.
+// Logs are accumulated during execution and dumped to standard error when done.
 type T struct {
        errors  string;
        failed  bool;
        ch      chan *T;
 }
 
+// Fail marks the Test function as having failed but continues execution.
 func (t *T) Fail() {
        t.failed = true
 }
 
+// FailNow marks the Test function as having failed and stops its execution.
+// Execution will continue at the next Test.
 func (t *T) FailNow() {
        t.Fail();
        t.ch <- t;
        sys.Goexit();
 }
 
+// Log formats its arguments using default formatting, analogous to Print(),
+// and records the text in the error log.
 func (t *T) Log(args ...) {
        t.errors += "\t" + tabify(fmt.Sprintln(args));
 }
 
+// Log formats its arguments according to the format, analogous to Printf(),
+// and records the text in the error log.
 func (t *T) Logf(format string, args ...) {
        t.errors += tabify(fmt.Sprintf("\t" + format, args));
        l := len(t.errors);
@@ -49,26 +66,32 @@ func (t *T) Logf(format string, args ...) {
        }
 }
 
+// Error is equivalent to Log() followed by Fail().
 func (t *T) Error(args ...) {
        t.Log(args);
        t.Fail();
 }
 
+// Errorf is equivalent to Logf() followed by Fail().
 func (t *T) Errorf(format string, args ...) {
        t.Logf(format, args);
        t.Fail();
 }
 
+// Fatal is equivalent to Log() followed by FailNow().
 func (t *T) Fatal(args ...) {
        t.Log(args);
        t.FailNow();
 }
 
+// Fatalf is equivalent to Logf() followed by FailNow().
 func (t *T) Fatalf(format string, args ...) {
        t.Logf(format, args);
        t.FailNow();
 }
 
+// An internal type but exported because it is cross-package; part of the implementation
+// of gotest.
 type Test struct {
        Name string;
        F func(*T);
@@ -79,6 +102,8 @@ func tRunner(t *T, test *Test) {
        t.ch <- t;
 }
 
+// An internal function but exported because it is cross-package; part of the implementation
+// of gotest.
 func Main(tests []Test) {
        flag.Parse();
        ok := true;