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

cmd/doc: show Bugs section #33970

Open
pascaldekloe opened this issue Aug 30, 2019 · 10 comments
Open

cmd/doc: show Bugs section #33970

pascaldekloe opened this issue Aug 30, 2019 · 10 comments

Comments

@pascaldekloe
Copy link
Contributor

@pascaldekloe pascaldekloe commented Aug 30, 2019

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

@agnivade agnivade commented Aug 30, 2019

Sounds reasonable to me.

@robpike @mvdan

@agnivade agnivade changed the title BUG documentation unavailable on command line cmd/doc: show Bugs section Aug 30, 2019
@agnivade agnivade added this to the Unplanned milestone Aug 30, 2019
@pascaldekloe
Copy link
Contributor Author

@pascaldekloe pascaldekloe commented Aug 30, 2019

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

@agnivade
Copy link
Contributor

@agnivade agnivade commented Aug 30, 2019

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

@mvdan
Copy link
Member

@mvdan mvdan commented Aug 30, 2019

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

@pascaldekloe pascaldekloe commented Aug 30, 2019

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

@mvdan mvdan commented Aug 30, 2019

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

@pascaldekloe pascaldekloe commented Aug 30, 2019

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

@robpike
Copy link
Contributor

@robpike robpike commented Aug 31, 2019

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

@agnivade agnivade commented Aug 31, 2019

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.

@pascaldekloe
Copy link
Contributor Author

@pascaldekloe pascaldekloe commented Aug 31, 2019

The strings package example has a BUG comment embedded into the function comment block. In that case go doc prints the bugs section indeed. However, the detection fails with the -all flag, and the comment block is printed as is, including (rsc) marker.

% go doc strings | tail -n 5
type Replacer struct{ ... }
    func NewReplacer(oldnew ...string) *Replacer

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

% go doc -all strings | grep -i bug -B 2 -A 3
    words mapped to their Unicode title case.

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

func ToLower(s string) string
% go doc github.com/pascaldekloe/jwt | grep -i bug
% ~/sdk/go1.11.6/bin/go !*
~/sdk/go1.11.6/bin/go doc github.com/pascaldekloe/jwt | grep -i bug
BUG: Some broken implementations fail to parse tokens
% 

So it turns out there are 32 issues.

  1. The -all flag disables bug comment detection.
  2. Go version 1.13 no longer detects bug comments in blocks.
  3. Go should include bug notes with a selection where applicable [new feature].

How to proceed? Shall I split this issue up into separate reports?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.