New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/tools/cmd/godoc: support linked examples #11397

Open
adg opened this Issue Jun 25, 2015 · 4 comments

Comments

Projects
None yet
4 participants
@adg
Contributor

adg commented Jun 25, 2015

Reviewing this CL I saw a cute thing done with related examples. In short:

func Example_a() int {
    return 42
}

func Example_b() {
    n := Example_a()
    fmt.Println(n)
}

func Example_c() {
    n := Example_a()
    fmt.Println(n)
}

It might be helpful for godoc to recognize this and show the user that the latter examples continue from the first one. I'm not sure exactly how that might look, but it's something to think about.

@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Jul 11, 2015

@meirf

This comment has been minimized.

Member

meirf commented May 26, 2018

I think the "dependency" should only be revealed when the example is revealed. Currently non-runnable examples just show "Code:" and then the block of code within the examples. Dependencies (there could be more than one) could be shown just above "Code:":

Dependencies: DB.Query, DB.QueryRow
Code:
...

To determine what the dependencies are we would have to choose between the user including some metadata (eg via comment) or by parsing the code.

Also it's not clear to me whether the current go official convention is to condone examples (even non-runnable ones) to return as Example_a does here. Perhaps we're totally fine with it. I noticed that GoLand gives a warning for this so I've created an issue with them: https://youtrack.jetbrains.com/issue/GO-5726 to determine if the warning is because of go or a bug on their end.

@agnivade ccing you since you've worked on godoc UI recently. (I assume you might not have seen this in the backlog due to its age or because the title uses "go/doc" instead of the more recent x/tools/cmd/godoc. Perhaps we should change the title to make this more easily searchable.)

@agnivade

This comment has been minimized.

Member

agnivade commented May 26, 2018

I assume you might not have seen this in the backlog due to its age or because the title uses "go/doc" instead of the more recent x/tools/cmd/godoc

The latter 😄

I'm not sure exactly how that might look

Neither do I. I can't see how this "linking" is going to be helpful, whatever that's supposed to look like. It's fine to use an Example function like a normal Go function and return from it. But it might be cleaner not to glean any special meaning out of it and just let it be.

@agnivade agnivade changed the title from go/doc: support linked examples to x/tools/cmd/godoc: support linked examples May 26, 2018

@meirf

This comment has been minimized.

Member

meirf commented May 26, 2018

It's fine to use an Example function like a normal Go function and return from it.

Looks like it's actually against go vet (probably -test) to have an example return anything:

./example_test.go:5: Example_a should return nothing

I don't know if this means we should close this issue, but if we want to keep it open go vet -test would need to be relaxed.

@agnivade

This comment has been minimized.

Member

agnivade commented May 26, 2018

Oh I see. Thanks for checking that.

Will leave it to others to decide what is to be done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment