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

Jump to bottom

x/tools/cmd/godoc: document behaviour of comments somewhere #28532

Open
KantarBruceAdams opened this issue Nov 1, 2018 · 6 comments
Open

x/tools/cmd/godoc: document behaviour of comments somewhere #28532

KantarBruceAdams opened this issue Nov 1, 2018 · 6 comments
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Unreleased

Comments

@KantarBruceAdams
Copy link

KantarBruceAdams commented Nov 1, 2018 •
edited

The good folks over at stackoverflow don't like my quite reasonable question asking where is the specification for godoc itself

The language specification doesn't mention that go:generate is special or that godoc comments exist.
The full rules should be documented somewhere other than in the gogenerate and godoc tools source.

Repeating that here:

I know godoc is minimal compared with similar tools but I would expect to find a specification for it somewhere. The closest thing to a specification I can find is the blog post announcing it. Is there anything more elsewhere? Even if there isn't a formal specificaiton perhaps a 1 page cheat sheet?

go help doc - documents the "go doc" sub-command but doesn't mention the format

This is also a hard thing to google as you get hits for anything documented using godoc.

I have found a couple of "tricks and tips" pages:

http://elliot.land/post/godoc-tips-tricks
https://godoc.org/github.com/fluhus/godoc-tricks

I know the source is available but I should not have to read the source (which also has no link to a spec) to know how to use the tool.

I am surprised that I should have to ask this question and also that no-one has asked already so perhaps I have missed something obvious?

Some things not mentioned in that blog post which may help show why a spec would help that I have stumbled upon are:

[titles](https://godoc.org/github.com/fluhus/godoc-tricks#titles) (as in link above)
[quotes](https://www.reddit.com/r/golang/comments/35ee2t/quotes_in_godoc/)

Extensions using go commands must not clash with the godoc syntax For example:

[gocontracts](https://github.com/Parquery/gocontracts extends the godoc syntax to support contracts in comments
[apidocjs](http://apidocjs.com/) allows you to embeds API documentation in go comments
go itself uses some comments semantically - e.g. "go: generate"

The language specification itself does not discuss the behaviour of comments beyond the syntax.
@ianlancetaylor
Copy link
Contributor

The docs are at http://golang.org/doc/articles/godoc_documenting_go_code.html . There is a link to that page from the godoc documentation at https://godoc.org/golang.org/x/tools/cmd/godoc .

It would help if you could point out areas where that could be improved. Thanks.

@ianlancetaylor ianlancetaylor changed the title document behaviour of comments somewhere x/tools/cmd/godoc: document behaviour of comments somewhere Nov 1, 2018
@gopherbot gopherbot added this to the Unreleased milestone Nov 1, 2018
@ianlancetaylor ianlancetaylor added the NeedsFix The path to resolution is known, but the work has not been done. label Nov 1, 2018
@KantarBruceAdams
Copy link
Author

That document is a great one page introduction. It is not a specification. A specification need not be very long but I think it would be useful. It could be similar to a cheat sheet.
The blog page does not:

  • say what comments will be interpreted by go tools like go doc and go generate.
  • It does not say whether it is legal to name the function twice.
    Will you get two comments or one comment with two bullet points?
  • Is it safe for third party tools gocontracts to try to extend the syntax by using "FuncName requires" to indicate a pre-condition or apidocjs (not a go tool but a tool that happens to support go) to do what it does.
  • Do different versions of go have different rules?
  • What are the reserved words? (at least "Deprecated: ", "BUG():" & "go:generate")

@agnivade
Copy link
Contributor

agnivade commented Nov 1, 2018

Some additional points here - https://golang.org/doc/effective_go.html#commentary.

@KantarBruceAdams
Copy link
Author

I just discovered build constraints as another semantic use of comments built into go

https://golang.org/pkg/go/build/#hdr-Build_Constraints

These really all should be documented together.
To an outsider it feels like a design smell that comments can be used for so many different things.

@KantarBruceAdams KantarBruceAdams mentioned this issue Nov 6, 2018
Open
@KantarBruceAdams
Copy link
Author

See also https://stackoverflow.com/questions/53487371/what-are-the-uses-of-semantic-comments-in-go

@ensonic
Copy link

ensonic commented Apr 29, 2019

Titles feature is not documented in the article
https://godoc.org/github.com/fluhus/godoc-tricks#Titles

@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
5 participants
@ensonic @agnivade @ianlancetaylor @gopherbot @KantarBruceAdams