code review 5657048: go/doc, godoc: regard lone examples as "whole file" examples

go/doc, godoc: regard lone examples as "whole file" examples

Fixes issue 2930.

[adg, 2012-02-14 00:43:35]

Hello r, gri (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://go.googlecode.com/hg

[rsc, 2012-02-14 00:46:57]

I can't tell what this is doing.  Documentation?

[gri, 2012-02-14 00:57:11]

LGTM

Some suggestions for variable renaming.

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go
File src/pkg/go/doc/example.go (right):

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode24
src/pkg/go/doc/example.go:24: var ex []*Example
s/ex/list/ ?

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode26
src/pkg/go/doc/example.go:26: onlyEx := true // does this file contain only
example code
var hasTests bool // true if the file contains tests and benchmarks, too

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode27
src/pkg/go/doc/example.go:27: var fileEx []*Example
s/fileEx/flist/ ?

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode35
src/pkg/go/doc/example.go:35: onlyEx = false
hasTests = true

[gri, 2012-02-14 00:58:45]

On Mon, Feb 13, 2012 at 4:46 PM, Russ Cox <rsc@golang.org> wrote:
> I can't tell what this is doing.  Documentation?

Makes it possible to have an entire package files as example, rather
then only a single function. Motivated by the heap example, I guess.
- gri

[rsc, 2012-02-14 01:07:58]

Even so, godoc testing should say this.

[adg, 2012-02-14 01:51:31]

On 2012/02/14 01:07:58, rsc wrote:
> Even so, godoc testing should say this.

Done, and updated go help testfunc too.

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go
File src/pkg/go/doc/example.go (right):

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode24
src/pkg/go/doc/example.go:24: var ex []*Example
On 2012/02/14 00:57:12, gri wrote:
> s/ex/list/ ?

Done.

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode26
src/pkg/go/doc/example.go:26: onlyEx := true // does this file contain only
example code
On 2012/02/14 00:57:12, gri wrote:
> var hasTests bool // true if the file contains tests and benchmarks, too

Done.

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode27
src/pkg/go/doc/example.go:27: var fileEx []*Example
On 2012/02/14 00:57:12, gri wrote:
> s/fileEx/flist/ ?

Done.

http://codereview.appspot.com/5657048/diff/1/src/pkg/go/doc/example.go#newcode35
src/pkg/go/doc/example.go:35: onlyEx = false
On 2012/02/14 00:57:12, gri wrote:
> hasTests = true

Done.

[r, 2012-02-14 05:20:52]

LGTM from a commentary perspective.

[adg, 2012-02-14 06:20:06]

*** Submitted as http://code.google.com/p/go/source/detail?r=561bc290532c ***

go/doc, godoc: regard lone examples as "whole file" examples

Fixes issue 2930.

R=r, gri, rsc
CC=golang-dev
http://codereview.appspot.com/5657048