code review 5440100: godoc: Allow examples for methods.

godoc: Allow examples for methods.

An example for a method M() of type T can be written as
func ExampleT_M() { ... }.
To differentiate between multiple examples for one function, type or
method a suffix with a lowercase start may be appended to the name
of the example function, e.g. ExampleFoo_basicUsage.

Fixes issue 2465.

[volker.dobler, 2011-12-05 10:24:03]

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

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

[adg, 2011-12-05 23:58:28]

I'm having second thoughts about the numbers-only restriction. What about this:

For a package containing type T with method M:
- ExampleT and ExampleT_x document T, where x is any name that is not a method
of T.
- ExampleT_M and ExampleT_M_x document T.M (for any x).

I would prefer that examples are given descriptive names, like ExampleSort,
ExampleSort_Reverse, ExampleSort_StructField, etc...

[r2, 2011-12-05 23:59:39]

Agree. I dislike the naming (numbering) convention introduced here. It's so
1963.

-rob

[adg, 2011-12-06 00:01:53]

http://codereview.appspot.com/5440100/diff/3001/src/cmd/godoc/godoc.go
File src/cmd/godoc/godoc.go (right):

http://codereview.appspot.com/5440100/diff/3001/src/cmd/godoc/godoc.go#newcod...
src/cmd/godoc/godoc.go:469: j := len(name) - 1
This code is a bit too intricate for my tastes. First split the string with
strings.SplitN then check each part individually. The for loop that checks for
numeric chars only would be better off in a separate function (although you'll
not need it with my proposal).

[volker.dobler, 2011-12-06 09:25:33]

Hello golang-dev@googlegroups.com, adg@golang.org, r@google.com (cc:
golang-dev@googlegroups.com),

Please take another look.

[volker.dobler, 2011-12-06 09:39:29]

On 2011/12/05 23:58:28, adg wrote:
> I'm having second thoughts about the numbers-only restriction. What about
this:
> 
> For a package containing type T with method M:
> - ExampleT and ExampleT_x document T, where x is any name that is not a
method
> of T.
> - ExampleT_M and ExampleT_M_x document T.M (for any x).
> 
> I would prefer that examples are given descriptive names, like ExampleSort,
> ExampleSort_Reverse, ExampleSort_StructField, etc...

I implemented the proposed naming conventions as it is more 
verbose and clearer.
Unfortunately it feels a bit strange, the solution is kind of 
a (unfinished) hack:

A)
I am not sure if providing the examples as a own structure
to the template is the right way: M aybe adding an example
slot to TypeDoc and FuncDoc in go/doc would be cleaner, even
if these slots are filled by cmd/gotest and not by go/doc.

B)
An example might be lost: If there is no function, type
or method which matches the example function name, the example
is just silently discarded. This could be just a typo:
Want to explain func Bar() but wrote ExampleBaz.
If these "unparented" examples are not output they could
be dropped earlier.

C)
The descriptive suffix (e.g. "Reverse" in ExampleSort_Reverse)
is not show in the example.  But if it is helpful in the
code, maybe it would be helpful in the example too...

[volker.dobler, 2011-12-06 22:35:11]

Hello golang-dev@googlegroups.com, adg@golang.org, r@google.com (cc:
golang-dev@googlegroups.com),

Please take another look.

[rsc, 2011-12-07 18:08:00]

We need a suffix that is unlikely to happen
in practice and does not have a meaning.

[0-9]+ has been rejected.
_[A-Z].* is ambiguous, so problematic.

What about _[a-z].*?
It's unambiguous because the methods
you'd want to use for examples will have
upper case names.

Russ

[volker.dobler, 2011-12-07 21:29:24]

On Wed, Dec 7, 2011 at 7:07 PM, Russ Cox <rsc@golang.org> wrote:

> We need a suffix that is unlikely to happen
> in practice and does not have a meaning.
>
> [0-9]+ has been rejected.
> _[A-Z].* is ambiguous, so problematic.
>

It is not problematic per se, it just adds some complexity in
distinguishing ExampleType_Something from ExampleType_Method.

>
> What about _[a-z].*?
> It's unambiguous because the methods
> you'd want to use for examples will have
> upper case names.
>

Fine for me:
  - ExampleType_lowercase would be a type example
  - ExampleType_UpperCase some method example (if UpperCase is a method)
  - ExampleType_UpperCase_anything a method example (if " )
  - The lowercase suffix can be descriptive as Andrew suggested.
  - Implementation would be like in Patch Set 3
http://codereview.appspot.com/5440100/#ps3001

On golang-nuts there where arguments against this kind of convention (which
is perfectly
fine for me)
http://groups.google.com/group/golang-nuts/msg/9a4962b25fd4e55a

I see just one stumbling block: If someone is unaware of the convention
(or just forgot it as _ and lowercase is not "idiomatic") and writes
ExampleType_Simple and ExampleType_Advanced he will not get
type example for simple and advanced usage but nothing if there
are no methods Simple and Advanced (in which case the examples
would be sorted to the methods whereas the current solution would sort them
properly to the type).

Volker

-- 
Dr. Volker Dobler

[rsc, 2011-12-07 21:34:55]

On Wed, Dec 7, 2011 at 16:29, Volker Dobler
<dr.volker.dobler@gmail.com> wrote:>   - ExampleType_lowercase would
be a type example>   - ExampleType_UpperCase some method example (if
UpperCase is a method)
It is a method example no matter what.It just might be an example of a
method that doesn't exist.  :-)
> I see just one stumbling block: If someone is unaware of the convention
> (or just forgot it as _ and lowercase is not "idiomatic") and writes
> ExampleType_Simple and ExampleType_Advanced he will not get
> type example for simple and advanced usage but nothing if there
> are no methods Simple and Advanced (in which case the examples
> would be sorted to the methods whereas the current solution would sort them
> properly to the type).

This is true of many things in the language, not least interfaces.
It's not a problem.

Russ

[volker.dobler, 2011-12-08 19:36:12]

Hello golang-dev@googlegroups.com, adg@golang.org, r@google.com, rsc@golang.org
(cc: golang-dev@googlegroups.com),

Please take another look.

[dupoxy, 2011-12-13 09:59:03]

On 2011/12/08 19:36:12, volker.dobler wrote:
> Hello mailto:golang-dev@googlegroups.com, mailto:adg@golang.org,
mailto:r@google.com, mailto:rsc@golang.org
> (cc: mailto:golang-dev@googlegroups.com),
> 
> Please take another look.
hello
this seems ok (but I'm not expert)
is there something not right ?

[r, 2011-12-14 04:52:08]

http://codereview.appspot.com/5440100/diff/10001/src/cmd/godoc/godoc.go
File src/cmd/godoc/godoc.go (right):

http://codereview.appspot.com/5440100/diff/10001/src/cmd/godoc/godoc.go#newco...
src/cmd/godoc/godoc.go:470: return unicode.IsLetter(r) && unicode.IsUpper(r)
you don't need to test both. IsUpper is sufficient. you don't even need to test
len(s) == 0, actually.

http://codereview.appspot.com/5440100/diff/10001/src/cmd/godoc/godoc.go#newco...
src/cmd/godoc/godoc.go:484: }
all you need to do is use strings.LastIndex and slice off the tail.

[volker.dobler, 2011-12-14 08:33:45]

Hello golang-dev@googlegroups.com, adg@golang.org, r@google.com, rsc@golang.org,
duperray.olivier@gmail.com, r@golang.org (cc: golang-dev@googlegroups.com),

Please take another look.

[volker.dobler, 2011-12-14 08:34:05]

http://codereview.appspot.com/5440100/diff/10001/src/cmd/godoc/godoc.go
File src/cmd/godoc/godoc.go (right):

http://codereview.appspot.com/5440100/diff/10001/src/cmd/godoc/godoc.go#newco...
src/cmd/godoc/godoc.go:470: return unicode.IsLetter(r) && unicode.IsUpper(r)
On 2011/12/14 04:52:08, r wrote:
> you don't need to test both. IsUpper is sufficient. you don't even need to
test
> len(s) == 0, actually.

Done.

http://codereview.appspot.com/5440100/diff/10001/src/cmd/godoc/godoc.go#newco...
src/cmd/godoc/godoc.go:484: }
On 2011/12/14 04:52:08, r wrote:
> all you need to do is use strings.LastIndex and slice off the tail.

Done.
The distinguishing suffix may no longer contain underscores.

[r, 2011-12-15 22:54:00]

seems OK to me. leaving for others.

http://codereview.appspot.com/5440100/diff/14002/src/cmd/gotest/doc.go
File src/cmd/gotest/doc.go (right):

http://codereview.appspot.com/5440100/diff/14002/src/cmd/gotest/doc.go#newcode45
src/cmd/gotest/doc.go:45: to the name.  The suffix must start with a lowercase
letter.
s/.$/ and may not contain underscores.

[adg, 2011-12-15 22:57:51]

LGTM

This is much nicer now. Sorry for the delayed review.

[adg, 2011-12-15 23:02:02]

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

godoc: Allow examples for methods.

An example for a method M() of type T can be written as
func ExampleT_M() { ... }.
To differentiate between multiple examples for one function, type or
method a suffix with a lowercase start may be appended to the name
of the example function, e.g. ExampleFoo_basicUsage.

Fixes issue 2465.

R=golang-dev, adg, r, rsc, duperray.olivier, r
CC=golang-dev
http://codereview.appspot.com/5440100

Committer: Andrew Gerrand <adg@golang.org>