cmd/doc: show Bugs section

[pascaldekloe]

The new go doc does not show documented bugs conform the convention.

For example, go doc -all godoc.org/pascaldekloe/jwt | grep -i bug has no results. The HTML representation catches the comments correctly at https://godoc.org/github.com/pascaldekloe/jwt#pkg-note-bug .

Bugs are an essential part of the documentation.

• go doc -all should have a bugs section (like godoc(8) does)
• go doc <selection> should include the relevant bugs for the respective selection

[agnivade]

Sounds reasonable to me.

@robpike @mvdan

[pascaldekloe]

Technically this is not a feature. The old godoc had bug listing on the command line.

[agnivade]

Right. But cmd/doc didn't. So it is a feature request for cmd/doc. But I get what you mean :).

[mvdan]

I assume that @ianthehat or @dmitshur have some ideas here, since I undesrtand they plan on sharing more code between similar tools like go doc and gddo.

[pascaldekloe]

The old go doc als listed bugs correctly @agnivade. I see now how my description is a bit misleading. This is a bug, or maybe an undocumented feature los. 😏

[mvdan]

Are you positive? If so, can you reproduce that with a specific old version of Go? For example, see https://godoc.org/golang.org/dl, or the Docker images.

[pascaldekloe]

Yes, version 1.11 of go doc (without any flags) reports the bugs section nicely.

[robpike]

It already mostly does this. Try 'go doc strings, or go doc -all strings, which is equivalent functionality to what the the godoc` server shows for the package, and you will see:

BUG: The rule Title uses for word boundaries does not handle Unicode punctuation properly.

If you are asking that the bug information be shown always, I disagree, as go doc TrimFunc should not display the output for a bug about Title.

What it does not do is show the bug if you explicitly ask about Title. That should be fixed.

[agnivade]

Aha ! It shows it as part of the function itself. I was searching for a separate section like godoc shows. My bad, I should have grepped for "BUG".

@robpike - Do you think it makes sense to move all BUGs and show them as a separate section at the bottom like godoc does ? Apart from also showing them when someone explicitly asks for that function/method.