Skip to content
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.

Sign up for GitHub

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

Jump to bottom

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

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

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

adg opened this issue Jun 25, 2015 · 4 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Unplanned

Comments

@adg
Copy link
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
Copy link
Contributor

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
Copy link
Contributor

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 go/doc: support linked examples x/tools/cmd/godoc: support linked examples May 26, 2018
@agnivade agnivade added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label May 26, 2018
@meirf
Copy link
Contributor

meirf commented May 26, 2018 •
edited

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
Copy link
Contributor

Oh I see. Thanks for checking that.

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

@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
5 participants
@agnivade @meirf @ianlancetaylor @adg @gopherbot