documentation change dropped an important part
Rob Pike
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.
-rob
=======
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) {