I noticed from a thread somewhere that the discussion of doc comments in Effective Go moved into a separate document when the formatting stuff went in. That's a fine idea.(Although I don't remember being consulted about it and I might have caught this if I was (or perhaps I just forgot and dropped the ball).)
One piece of it seems to have fallen on the floor. There is nothing in the new Effective Go or the new web page that describes the English style Go comments should have, the convention they should follow and why that's the right thing to do.
I include the missing piece from 2009. I still can't find the reasoning though. It has to do with using search to find things in the files, something perhaps of lesser importance nowadays because of the prevalence of IDEs.
It would be nice to restore this somewhere, or perhaps in both locations.
=======
Doc comments work best as complete English sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared.
// Compile parses a regular expression and returns, if successful, a Regexp
// object that can be used to match against text.
func Compile(str string) (regexp *Regexp, error os.Error) {
Comment From: thepudds
I still can't find the reasoning though. It has to do with using search to find things in the files,
Hi @robpike, I don't know if this is helpful, but two quick comments:
First, the https://go.dev/doc/comment#type page currently contains a little about search (emphasis added):
As with packages (above) and funcs (below), doc comments for types start with complete sentences naming the declared symbol. An explicit subject often makes the wording clearer, and it makes the text easier to search, whether on a web page or a command line. For example:
$ go doc -all regexp | grep pairs pairs within the input string: result[2n:2n+2] identifies the indexes
Second, maybe the rationale was on the wiki at one point? The wiki does contain some comment-related advice, but I don't see any search-related rationale for comment style there based on some quick poking around just now. Here for example is a snippet from an early commit (shortly after importing the wiki from Google Code) for the CodeReviewComments wiki page:
Comment Sentences
See http://golang.org/doc/effective_go.html#commentary. Comments documenting declarations should be full sentences, even if that seems a little redundant. This approach makes them format well when extracted into godoc documentation.
Comment From: mrkfrmn
CC @golang/tools-team from owners.
Comment From: findleyr
For reference, the CL that migrated the discussion of doc comments is https://go.dev/cl/410394.
I agree that the new text is less clear about the general structure of doc comments, though as @thepudds points out the major points seem to be present within subsections.
I think we should add an additional paragraph to the introduction of go.dev/doc/comment describing style and conventions that apply to all doc comments, and remove some of the redundancy of individual subsections.