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: example should jump to signature, not example proper #4919

Open
robpike opened this Issue Feb 26, 2013 · 18 comments

Comments

Projects
None yet
8 participants
@robpike
Contributor

robpike commented Feb 26, 2013

In godoc, I would prefer if the link that jumps to the
example instead jumped to the function, so we see a reminder of the
signature and doc comment for the function before the example. It's
usually only a few lines.

For example, jump to /pkg/unicode/utf8/#DecodeLastRune rather than
/pkg/unicode/utf8/#example_DecodeLastRune
@rsc

This comment has been minimized.

Contributor

rsc commented Mar 12, 2013

Comment 1:

[The time for maybe has passed.]

Labels changed: removed go1.1maybe.

@adg

This comment has been minimized.

Contributor

adg commented Mar 18, 2013

Comment 2:

Labels changed: added godoc.

@rsc

This comment has been minimized.

Contributor

rsc commented Nov 27, 2013

Comment 3:

Labels changed: added go1.3maybe.

@rsc

This comment has been minimized.

Contributor

rsc commented Dec 4, 2013

Comment 4:

Labels changed: added release-none, removed go1.3maybe.

@rsc

This comment has been minimized.

Contributor

rsc commented Dec 4, 2013

Comment 5:

Labels changed: added repo-tools.

@gopherbot

This comment has been minimized.

gopherbot commented May 23, 2014

Comment 6:

CL https://golang.org/cl/97690045 mentions this issue.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015

@rsc rsc changed the title from cmd/godoc: example should jump to signature, not example proper to x/tools/cmd/godoc: example should jump to signature, not example proper Apr 14, 2015

@rsc rsc removed the repo-tools label Apr 14, 2015

@adg adg removed their assignment May 27, 2016

@adg adg added the help wanted label May 27, 2016

@gopherbot

This comment has been minimized.

gopherbot commented Jun 29, 2016

CL https://golang.org/cl/24580 mentions this issue.

@iamnande

This comment has been minimized.

iamnande commented Jun 30, 2016

Hi there,

I made CL 24580, which I believe is a redo of the fix in a previous change system. If any further work is necessary I'm willing to make an effort to fulfill. My first CL for any go project, feel free to tell me if anything is amiss.

@gopherbot

This comment has been minimized.

gopherbot commented Jul 1, 2016

CL https://golang.org/cl/24712 mentions this issue.

@gopherbot

This comment has been minimized.

gopherbot commented Jul 1, 2016

CL https://golang.org/cl/24713 mentions this issue.

@gopherbot

This comment has been minimized.

gopherbot commented Jul 1, 2016

CL https://golang.org/cl/24714 mentions this issue.

@ysmolsky

This comment has been minimized.

Member

ysmolsky commented Feb 21, 2018

I just checked it here https://golang.org/pkg/unicode/utf8/ and here https://golang.org/pkg/bufio/ - all example links work as expected.
Perhaps, close it?
CC: @adg

@agnivade

This comment has been minimized.

Member

agnivade commented Feb 22, 2018

@ysmolsky - The issue is about jumping to the function signature instead of the example. So, if you go to https://golang.org/pkg/unicode/utf8/ and click on "DecodeLastRune" under the Examples section - it should jump to https://golang.org/pkg/unicode/utf8/#DecodeLastRune instead of https://golang.org/pkg/unicode/utf8/#example_DecodeLastRune.

It is still not implemented currently as I see it.

@ysmolsky

This comment has been minimized.

Member

ysmolsky commented Feb 23, 2018

I can make it work technically for the examples of functions and methods. But I don't know what should be the behaviour when there are multiple examples per type/method: https://golang.org/pkg/bufio/#pkg-examples, https://golang.org/pkg/database/sql/#pkg-examples.

In the case of https://golang.org/pkg/bufio/#example_Scanner_custom it is obvious that we can jump to type Scanner and expand the example below. But what to do with https://golang.org/pkg/bufio/#example_Scanner_emptyFinalToken? And what about DB.Query (MultipleResultSets)?

I do not see an elegant and consistent behaviour here. Help?

@agnivade

This comment has been minimized.

Member

agnivade commented Apr 23, 2018

But what to do with https://golang.org/pkg/bufio/#example_Scanner_emptyFinalToken? And what about DB.Query (MultipleResultSets)?

Going with the spirit of the issue, I think it should always jump to the parent type/method.

FWIW, I think this leads to counter-intuitive (and possibly confusing) behavior. If I click on an example anchor, it should lead me to the example. Straight and simple. If I wanted to know about the function, I would have clicked the function anchor.

This also makes examples more difficult to share. If I wanted to show an example of bufio wordcount (https://golang.org/pkg/bufio/#example_Scanner_words) and share the link, but it instead links to the documentation of the Scanner struct, that would be extremely confusing.

@ysmolsky

This comment has been minimized.

Member

ysmolsky commented Apr 23, 2018

@agnivade exactly my thoughts, trying to fix this I was making it more confusing. More over, I could not find simple and elegant solution which would be consistent. Some old issues are like that, doomed a little. :-(

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Apr 23, 2018

The current behavior is best. Example X should link to Example X. However, there could be a link to what the example is attached to at the start of the example to allow quickly jumping to the signature. This works whether the documentation is terse or verbose and regardless of the number of examples.

With something like that in place, you could follow the link to the 7th example of Foo, it opens as it normally does. If you want to see the signature click the link and when you navigate back you'll be at the example again.

@agnivade

This comment has been minimized.

Member

agnivade commented Apr 23, 2018

However, there could be a link to what the example is attached to at the start of the example to allow quickly jumping to the signature. This works whether the documentation is terse or verbose and regardless of the number of examples.

Fair enough. I have a related issue here #17223 where I propose to expose a link for the example too. I can probably add what you are suggesting along with it.

I think we all agree that implementing the current solution as is, will cause more confusion than benefit. Plus, it's 5 years old :) Will leave it to @robpike for final thoughts.

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