Examples

[Volker Dobler]

I tried to fix some of the issues regarding godoc, especially issues
with the examples (Issues 2467, 2466, 2465, 2464).

And found three things with multiple examples for one item
which I'd like to discuss before sending a CL:

A) Currently if more than one example is present for a function
both get their own a "> Example" fold-out which feels strange
as there might be three "> Examples" and you cannot tell which
one you are interested in.
I tried and included all examples into one fold-out which gets
labeled "> Examples" if there are two or more.
Is this considered useful/appropriate?

B) Currently multiple examples for the same item (func, type)
can be defined by suffixing them with "_.*". (Works well).
To add examples to methods Russ suggested in
http://code.google.com/p/go/issues/detail?id=2465
to name the examples like
func ExampleType_Method()
which interferes with the "use distinct _-suffixes" mentioned
above. I see two solutions which wouldn't need complete
reworking of godocs example mechanism:
1. Name examples for methods like
func ExampleTypeMethod() and hope there
isn't a function
func TypeMethod(...)
2. Restrict the "distinguishing suffixes" to numbers only:
func ExampleFunction()
func ExampleFunction_2()
func ExampleFunction_3()
func ExampleType_()
func ExampleType_2()
func ExampleType_Method()
func ExampleType_Method_2()
which has the advantage that it is unambiguous as there
are no functions/methods named with a letter and the
disadvantage that this imposes a restriction on the nameing
of several examples for one item.

C) Just to be sure: What is the preferred way: Little CLs,
one for each issue, or better one CL (a bit larger) for each
issue?

Volker

[Jan Mercl]

On Thursday, December 1, 2011 3:19:07 PM UTC+1, Volker Dobler wrote:

I tried to fix some of the issues regarding godoc, especially issues
with the examples (Issues 2467, 2466, 2465, 2464).

And found three things with multiple examples for one item
which I'd like to discuss before sending a CL:

A) Currently if more than one example is present for a function
both get their own a "> Example" fold-out which feels strange
as there might be three "> Examples" and you cannot tell which
one you are interested in.

How many multi example cases are currently found in the whole tree? Because if zero or just few than it's a non problem.

 

I tried and included all examples into one fold-out which gets
labeled "> Examples" if there are two or more.
Is this considered useful/appropriate?

I prefer, in the case where there is more than one example, to be each separately clickable, e.g. how it is now. I guestimate the average number of examples to be like 1.1, where they are/will be at all.

Defining more and more "metalanguages" over number of blank lines in comments, over last rune in a line, over names of functions (Test*, Benchamark*, ...) should be IMHO avoided at all cost except when really Really REALLY needed (which IMO the already defined cases for tests, benchmarks and examples are). The idea of adding more and more such magic indentifiers/rules only because of making something look a little bit "better" in an HTML browser (and only in a HTML browser) really scares me.

-INF

 

C) Just to be sure: What is the preferred way: Little CLs,
one for each issue, or better one CL (a bit larger) for each
issue?

Iff approved here by the dev team before the CL arriving - I hope.

[Andrew Gerrand]

I wrote the original example code support, but haven't had a chance to write the examples yet.

I appreciate your help with fixing these issues.

On Friday, December 2, 2011 1:19:07 AM UTC+11, Volker Dobler wrote:

I tried to fix some of the issues regarding godoc, especially issues
with the examples (Issues 2467, 2466, 2465, 2464).

And found three things with multiple examples for one item
which I'd like to discuss before sending a CL:

A) Currently if more than one example is present for a function
both get their own a "> Example" fold-out which feels strange
as there might be three "> Examples" and you cannot tell which
one you are interested in.
I tried and included all examples into one fold-out which gets
labeled "> Examples" if there are two or more.
Is this considered useful/appropriate?

That sounds fine to me.

I think it's fine to restrict the naming of successive examples to numbers only. This was actually in my original design but we generalized it because there wasn't a rationale for restricting it to numbers. Now there. is

 

C) Just to be sure: What is the preferred way: Little CLs,
one for each issue, or better one CL (a bit larger) for each
issue?

Please split your CLs into logical pieces, if possible. Ideally each change should be about accomplishing one specific thing. It's okay to group  changes together if they depend on each other, but don't send several independent changes in the one CL.

Andrew