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.

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/pkgsite/internal/fetch/dochtml, x/tools/cmd/godoc: BUG, TODO etc. should be re-thought #5060

Open
robpike opened this issue Mar 16, 2013 · 6 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite UX Issues that involve UXD/UXR input
Milestone

Comments

@robpike
Copy link
Contributor

robpike commented Mar 16, 2013

Godoc needs updated rules and a nice UI for interpreting and presenting BUG(foo),
TODO(bar) etc. The current setup is odd: it treats things internal to functions
specially, while things at top level are too loosely bound. For instance,

// Foo bars blatz.
// BUG(gopher): Foo should bing bang bam.
func Foo() { } 

will fold the TODO onto the previous line, while

// BUG(gopher): Foo should bing bang bam.

// Foo bars blatz.
func Foo() { } 

will print the BUG for every query of the package. This is far from intuitive or helpful.
@adg
Copy link
Contributor

adg commented Mar 18, 2013

Comment 1:

Labels changed: added godoc.

@gopherbot
Copy link

Comment 2 by pedromorgan:

Yes its strange.. And godoc.org completely ignores them

@griesemer
Copy link
Contributor

Comment 3:

At the moment, notes are collected from all comments in the source _but_ the comments
that are declaration documentation. That is, all comments that declare an exported item
stay with that item. So if that (group of) comments contains a TODO, BUG, etc. that part
of the comment is simply untouched and shown with the comment.
All otherwise discarded comments are then searched for notes, which are always shown
separately and collectively. There is no association with any specific entity. There is
no difference between notes inside function and notes on the package level as long as
the latter are "free-floating", i.e., not associated with any declaration documentation.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 5:

Labels changed: added repo-tools.

@rsc
Copy link
Contributor

rsc commented Mar 3, 2014

Comment 6:

Adding Release=None to all Priority=Someday bugs.

Labels changed: added release-none.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015
@rsc rsc changed the title cmd/godoc: BUG, TODO etc. should be re-thought x/tools/cmd/godoc: BUG, TODO etc. should be re-thought Apr 14, 2015
@rsc rsc removed the repo-tools label Apr 14, 2015
@dmitshur dmitshur added pkgsite NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. UX Issues that involve UXD/UXR input labels Jun 26, 2020
@dmitshur dmitshur changed the title x/tools/cmd/godoc: BUG, TODO etc. should be re-thought x/pkgsite/internal/fetch/dochtml, x/tools/cmd/godoc: BUG, TODO etc. should be re-thought Jun 26, 2020
@dmitshur
Copy link
Contributor

And godoc.org completely ignores them

This might've been true at the time that comment was made (in 2013), but by now, they are displayed on godoc.org as well as on pkg.go.dev.

a nice UI for [...] presenting BUG(foo), TODO(bar) etc.

Various websites that display Go package documentation so far have used slightly different URL schemes for linking to these sections. Compare:

Pkg.go.dev has so far followed suit from x/tools/cmd/godoc, but perhaps it would be better to make the fragment in the URL lower case. These URLs are used relatively infrequently, so if there can be a usability improvement made, it might not be too late. As more time passes, it becomes more expensive to make any change, and the current scheme is more likely to stay.

/cc @julieqiu

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite UX Issues that involve UXD/UXR input
Projects
None yet
Development

No branches or pull requests

6 participants