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

[KantarBruceAdams]

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]

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.

[KantarBruceAdams]

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]

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

[KantarBruceAdams]

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]

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

[ensonic]

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

[seankhliao]

doc comments are now more standardized https://go.dev/doc/comment

[tojamrok]

This still is an issue. There's no single place which would tell me what is a Golang comment and what is not. I stumbled across build tags, //go:, #cgo opening up a new context when combined with import "C" but there might be other dragons which I'm unaware of.