go/doc: move Examples to go/ast
cmd/go: use go/doc to read examples
src/pkg: update examples to use new convention
This is to make whole file examples more readable. When presented as a
complete function, preceding an Example with its output is confusing.
The new convention is to put the expected output in the final comment
of the example, preceded by the string "output:" (case insensitive).
An idiomatic example looks like this:
// This example demonstrates Foo by doing bar and quux.
func ExampleFoo() {
// example body that does bar and quux
// Output:
// example output
}
R=rsc, gri
CC=golang-dev
https://golang.org/cl/5673053
It's not as pretty, but it deletes some irrelevant information from the
printout and avoids a dependency.
It also means the test binary will stop if a test panics. That's a feature,
not a bug.
Any output printed by the test appears before the panic traceback.
before:
--- FAIL: TestPanic (0.00 seconds)
fmt_test.go:19: HI
testing.go:257: runtime error: index out of range
/Users/r/go/src/pkg/testing/testing.go:257 (0x23998)
_func_003: t.Logf("%s\n%s", err, debug.Stack())
/Users/r/go/src/pkg/runtime/proc.c:1388 (0x10d2d)
panic: reflect·call(d->fn, d->args, d->siz);
/Users/r/go/src/pkg/runtime/runtime.c:128 (0x119b0)
panicstring: runtime·panic(err);
/Users/r/go/src/pkg/runtime/runtime.c:85 (0x11857)
panicindex: runtime·panicstring("index out of range");
/Users/r/go/src/pkg/fmt/fmt_test.go:21 (0x23d72)
TestPanic: a[10]=1
/Users/r/go/src/pkg/testing/testing.go:264 (0x21b75)
tRunner: test.F(t)
/Users/r/go/src/pkg/runtime/proc.c:258 (0xee9e)
goexit: runtime·goexit(void)
FAIL
after:
--- FAIL: TestPanic (0.00 seconds)
fmt_test.go:19: HI
panic: runtime error: index out of range [recovered]
panic: (*testing.T) (0xec3b0,0xf8400001c0)
goroutine 2 [running]:
testing._func_003(0x21f5fa8, 0x21f5100, 0x21f5fb8, 0x21f5e88)
/Users/r/go/src/pkg/testing/testing.go:259 +0x108
----- stack segment boundary -----
fmt_test.TestPanic(0xf8400001c0, 0x27603728)
/Users/r/go/src/pkg/fmt/fmt_test.go:21 +0x6b
testing.tRunner(0xf8400001c0, 0x18edb8, 0x0, 0x0)
/Users/r/go/src/pkg/testing/testing.go:264 +0x6f
created by testing.RunTests
/Users/r/go/src/pkg/testing/testing.go:343 +0x76e
goroutine 1 [chan receive]:
testing.RunTests(0x2000, 0x18edb8, 0x2400000024, 0x100000001, 0x200000001, ...)
/Users/r/go/src/pkg/testing/testing.go:344 +0x791
testing.Main(0x2000, 0x18edb8, 0x2400000024, 0x188a58, 0x800000008, ...)
/Users/r/go/src/pkg/testing/testing.go:275 +0x62
main.main()
/var/folders/++/+++Fn+++6+0++4RjPqRgNE++2Qk/-Tmp-/go-build743922747/fmt/_test/_testmain.go:129 +0x91
exit status 2
R=rsc, dsymonds
CC=golang-dev
https://golang.org/cl/5658048
Among other things, this avoids putting a testing.go:nnn:
prefix on every line of the stack trace.
R=golang-dev, r, dsymonds, r
CC=golang-dev
https://golang.org/cl/5651081
Consequently, remove many package Makefiles,
and shorten the few that remain.
gomake becomes 'go tool make'.
Turn off test phases of run.bash that do not work,
flagged with $BROKEN. Future CLs will restore these,
but this seemed like a big enough CL already.
R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5601057
So as to give out stack trace for panic in examples.
This behavior also matches the tests'.
Fixes#2691.
R=golang-dev
CC=golang-dev
https://golang.org/cl/5554061
The package documentation did not mention them.
They were described only in godoc for gotest, and that's going away.
R=golang-dev, rsc, adg
CC=golang-dev
https://golang.org/cl/5539079
In a test that does
func TestFoo(t *testing.T) {
defer cleanup()
t.Fatal("oops")
}
it can be important that cleanup run as the test fails.
The old code did this in Fatal:
t.signal <- t
runtime.Goexit()
The runtime.Goexit would run the deferred cleanup
but the send on t.signal would cause the main test loop
to move on and possibly even exit the program before
the runtime.Goexit got a chance to run.
This CL changes tRunner (the top stack frame of a test
goroutine) to send on t.signal as part of a function
deferred by the top stack frame. This delays the send
on t.signal until after runtime.Goexit has run functions
deferred by the test itself.
For the above TestFoo, this CL guarantees that cleanup
will run before the test binary exits.
This is particularly important when cleanup is doing
externally visible work, like removing temporary files
or unmounting file systems.
R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5532078
Refactors the benchmarks and test code.
Now benchmarks can call Errorf, Fail, etc.,
and the runner will act accordingly.
Because functionality has been folded into an
embedded type, a number of methods' docs
no longer appear in godoc output. A fix is
underway; if it doesn't happen fast enough,
I'll add wrapper methods to restore the
documentation.
R=bradfitz, adg, rsc
CC=golang-dev
https://golang.org/cl/5492060
Errors in the code under test go to standard output.
Errors in testing or its usage go to standard error.
R=r
CC=golang-dev
https://golang.org/cl/5374090
This CL introduces the go.Example type and go.Examples functions that
are used to represent and extract code samples from Go source.
They should be of the form:
// Output of this function.
func ExampleFoo() {
fmt.Println("Output of this function.")
}
It also modifies godoc to read example code from _test.go files,
and include them in the HTML output with JavaScript-driven toggles.
It also implements testing of example functions with gotest.
The stdout/stderr is compared against the output comment on the
function.
This CL includes examples for the sort.Ints function and the
sort.SortInts type. After patching this CL in and re-building go/doc
and godoc, try
godoc -http=localhost:6060
and visit http://localhost:6060/pkg/sort/
R=gri, r, rsc
CC=golang-dev
https://golang.org/cl/5137041
It makes it clear what benchmark is currently running.
Especially useful in case of hangup or crash.
R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/4816043
Change the signature of Split to have no count,
assuming a full split, and rename the existing
Split with a count to SplitN.
Do the same to package bytes.
Add a gofix module.
R=adg, dsymonds, alex.brainman, rsc
CC=golang-dev
https://golang.org/cl/4661051
Reader previously had cached an error from the underlying reader
and would return it on every subsequent call to Read. The Reader
will now return the error only once, and subsequent calls will result
in a new Read call to the underlying Reader.
Fixes#1934.
R=bradfitz, rogpeppe, rsc
CC=golang-dev
https://golang.org/cl/4528133
-test.benchtime allows to specify benchmark execution time.
-test.cpu allows to execute tests/benchmarks for several
values of GOMAXPROCS.
R=r, r, rsc
CC=golang-dev
https://golang.org/cl/4662046
Plus fix spoiling of GOMAXPROCS in 2 existing rwmutex tests.
Plus fix benchmark output to stdout (now it outputs to stderr like all other output).
R=rsc
CC=golang-dev
https://golang.org/cl/4529111
We replace the current Open with:
OpenFile(name, flag, perm) // same as old Open
Open(name) // same as old Open(name, O_RDONLY, 0)
Create(name) // same as old Open(name, O_RDWR|O_TRUNC|O_CREAT, 0666)
This CL includes a gofix module and full code updates: all.bash passes.
(There may be a few comments I missed.)
The interesting packages are:
gofix
os
Everything else is automatically generated except for hand tweaks to:
src/pkg/io/ioutil/ioutil.go
src/pkg/io/ioutil/tempfile.go
src/pkg/crypto/tls/generate_cert.go
src/cmd/goyacc/goyacc.go
src/cmd/goyacc/units.y
R=golang-dev, bradfitzwork, rsc, r2
CC=golang-dev
https://golang.org/cl/4357052
Since Go code can deadlock, this lets a testsuite driver set a
time limit for the test to run. This is simple but imperfect,
in that it only catches deadlocks in Go code, not in the
runtime scheduler.
R=r, rsc, iant2
CC=golang-dev
https://golang.org/cl/4326048
New make target "testshort" runs "gotest -test.short" and is invoked
by run.bash, which is invoked by all.bash.
Use -test.short to make one package (crypto ecdsa) run much faster.
More changes to come.
Once this is in, I will update the long-running tests to use the new flag.
R=rsc
CC=golang-dev
https://golang.org/cl/4317043
Flags defined in the testing package may conflict
with real flags defined in the main package, or in
any other imported package.
This change makes them less likely to be used for
other purposes.
R=r, rsc, r2
CC=golang-dev
https://golang.org/cl/4167055
Rather than updating the stripped-down regexp implementation embedded
in testing, delete it by passing the one function we need from the package
main file created by gotest.
R=rsc
CC=golang-dev
https://golang.org/cl/2761043
New logging interface simplifies and generalizes.
1) Loggers now have only one output.
2) log.Stdout, Stderr, Crash and friends are gone.
Logging is now always to standard error by default.
3) log.Panic* replaces log.Crash*.
4) Exiting and panicking are not part of the logger's state; instead
the functions Exit* and Panic* simply call Exit or panic after
printing.
5) There is now one 'standard logger'. Instead of calling Stderr,
use Print etc. There are now triples, by analogy with fmt:
Print, Println, Printf
What was log.Stderr is now best represented by log.Println,
since there are now separate Print and Println functions
(and methods).
6) New functions SetOutput, SetFlags, and SetPrefix allow global
editing of the standard logger's properties. This is new
functionality. For instance, one can call
log.SetFlags(log.Lshortfile|log.Ltime|log.Lmicroseconds)
to get all logging output to show file name, line number, and
time stamp.
In short, for most purposes
log.Stderr -> log.Println or log.Print
log.Stderrf -> log.Printf
log.Crash -> log.Panicln or log.Panic
log.Crashf -> log.Panicf
log.Exit -> log.Exitln or log.Exit
log.Exitf -> log.Exitf (no change)
This has a slight breakage: since loggers now write only to one
output, existing calls to log.New() need to delete the second argument.
Also, custom loggers with exit or panic properties will need to be
reworked.
All package code updated to new interface.
The test has been reworked somewhat.
The old interface will be removed after the new release.
For now, its elements are marked 'deprecated' in their comments.
Fixes#1184.
R=rsc
CC=golang-dev
https://golang.org/cl/2419042
parsing and printing to new syntax.
Use -oldparser to parse the old syntax,
use -oldprinter to print the old syntax.
2) Change default gofmt formatting settings
to use tabs for indentation only and to use
spaces for alignment. This will make the code
alignment insensitive to an editor's tabwidth.
Use -spaces=false to use tabs for alignment.
3) Manually changed src/exp/parser/parser_test.go
so that it doesn't try to parse the parser's
source files using the old syntax (they have
new syntax now).
4) gofmt -w src misc test/bench
5th and last set of files.
R=rsc
CC=golang-dev
https://golang.org/cl/180050
- no need to replace comments for stand-alone blocks
- always print string concatenations with interspersed "+"
(remove option)
- minor cleanups
R=rsc
https://golang.org/cl/174076
the bash scripts and makefiles for building go didn't take into account
the fact $GOROOT / $GOBIN could both be directories containing whitespaces,
and was not possible to build it in such a situation.
this commit adjusts the various makefiles/scripts to make it aware of that
possibility, and now it builds successfully when using a path with whitespaces
as well.
Fixes#115.
R=rsc, dsymonds1
https://golang.org/cl/157067
No benchmarks are run unless the --benchmarks=<regexp> flag
is specified on the gotest command line. This change includes
sample benchmarks for regexp.
% gotest --benchmarks=.*
(standard test output redacted)
testing.BenchmarkSimpleMatch 200000 7799 ns/op
testing.BenchmarkUngroupedMatch 20000 76898 ns/op
testing.BenchmarkGroupedMatch 50000 38148 ns/op
R=r, rsc
https://golang.org/cl/154173
- enabled for function declarations (not just function literals)
- applied gofmt -w $GOROOT/src
(look for instance at src/pkg/debug/elf/elf.go)
R=r, rsc
CC=go-dev
http://go/go-review/1026006