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

Open
KantarBruceAdams opened this Issue Nov 1, 2018 · 5 comments

Comments

Projects
None yet
4 participants
@KantarBruceAdams

KantarBruceAdams 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:

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

This comment has been minimized.

Contributor

ianlancetaylor commented Nov 1, 2018

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 from document behaviour of comments somewhere to x/tools/cmd/godoc: document behaviour of comments somewhere Nov 1, 2018

@gopherbot gopherbot added this to the Unreleased milestone Nov 1, 2018

@KantarBruceAdams

This comment has been minimized.

KantarBruceAdams 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")
@agnivade

This comment has been minimized.

Member

agnivade commented Nov 1, 2018

@KantarBruceAdams

This comment has been minimized.

KantarBruceAdams commented Nov 2, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment