x/pkgsite/internal/fetch/dochtml: BUG, TODO etc. should be re-thought #5060
Comments
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. |
robpike
added
accepted
Documentation
rsc
changed the title
dmitshur
added
pkgsite
NeedsInvestigation
dmitshur
changed the title
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.
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 |
seankhliao
changed the title
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.The text was updated successfully, but these errors were encountered: