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/tools/cmd/godoc: document behaviour of comments somewhere #28532

KantarBruceAdams opened this issue Nov 1, 2018 · 6 comments


Copy link

commented Nov 1, 2018

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:

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]( (as in link above)

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

[gocontracts]( extends the godoc syntax to support contracts in comments
[apidocjs]( 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.


This comment has been minimized.

Copy link

commented Nov 1, 2018

The docs are at . There is a link to that page from the godoc documentation at .

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

This comment has been minimized.

Copy link

commented Nov 1, 2018

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")

This comment has been minimized.

Copy link

commented Nov 1, 2018


This comment has been minimized.

Copy link

commented Nov 2, 2018

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

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.


This comment has been minimized.

Copy link

commented Apr 29, 2019

Titles feature is not documented in the article

@gopherbot gopherbot added the Tools label Sep 12, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
5 participants
You can’t perform that action at this time.