How do you personally document functions in Golang?

<p>I know that for most documentation generating programs like Doxygen they want you to use a certain style to ensure maximum usefulness. So you might format the comments above your function to include the function name, return types, etc. so that Doxygen can pick it up correctly.</p> <p>Now, I realize with Go that you don&#39;t have to do all of that. Furthermore, I realize that whatever comments you leave before a function declaration will get picked up. But I suppose I&#39;m still just a little curious as to what everyone else is doing. How do you write comments regarding your functions? </p> <p>Is there a Go-approved style? Should you preface the comment with the function name? Include the inputs/outputs? Anything? So tell me, what do you guys do?</p> <hr/>**评论：**<br/><br/>TheMerovius: <pre><p><a href="http://blog.golang.org/godoc-documenting-go-code">This blog post</a> gives some overview. <a href="http://golang.org/doc/effective_go.html#commentary">Effective go</a> also has some guideluines. The <a href="https://github.com/golang/go/wiki/CodeReviewComments#comment-sentences">Code review comments</a> have <a href="https://github.com/golang/go/wiki/CodeReviewComments#doc-comments">something</a> to say too. In comparison to doxygen, the <a href="https://github.com/golang/go/wiki/CodeReviewComments#named-result-parameters">comment about named return values</a> is probably usefull too.</p> <p>My personal style is: I try <em>really</em> hard to make the signature of my function self-explanatory, adding names to <del>variables</del> parameters where they are not clear. If I don&#39;t think the signature alone is enough to know what the different parameters do, I add a textual description, weaving in the names of parameters. The <a href="http://golang.org/pkg/io/#Reader">stdlib</a> has <a href="http://golang.org/pkg/strings/#Index">some</a> <a href="http://golang.org/pkg/math/big/#Int.Bit">examples</a> of that too, that are very good, I think.</p> <p><em>Please</em> don&#39;t take bad habbits from doxygen. Don&#39;t write fancy banners, don&#39;t write decorated fixed-format descriptions of parameters (most of which should be pretty much self-explanatory anyway) or return value, lest annotated with a type (<em>ugh</em>. The type is already in the signature).</p> <p>You should write your function/method comments as good comments for the function/method they document. You should take into account, that everyone who will see your documentation will look at the signature of your function/method <em>first</em> and <em>foremost</em>, so make that count.</p> <p>And, just because golint complains otherwise, I don&#39;t know if it&#39;s mentioned above: The godoc-comment for Foo should start with Foo (as in &#34;Foo gets bar from baz and returns fnord&#34;), even if it is repetitive and kind of silly (as in &#34;Foo implements the Fooer interface&#34; or &#34;GetFnord gets a fnord&#34;). The consistency outweighs the silliness.</p></pre>burningEyeballs: <pre><p>Thanks very much for the detailed reply. I&#39;ll start reading those links now.</p></pre>barsonme: <pre><p>From what I&#39;m working on right now...</p> <pre><code>// InitStore initializes the default sessions.CookieStore with the given options. // keyPairs should be alternating authentication and encryption keys. E.g., // InitStore(opts, auth1, enc1, auth2, enc2 ...) // Repeated calls have no effect; it will only run once. func InitStore(opts *sessions.Options, keyPairs ...[]byte) { once.Do(func() { ... }) } </code></pre> <p>Simple, sweet and to the point. </p></pre>jerf: <pre><p>I try to make it look like the godoc that ships with the base system, including making it golint clean. The hypothetical ideal is that a library could be picked up and put in the base system, and other than the &#34;what the heck is <em>that</em> bit of functionality doing in the shipped base libraries?&#34; question, not look out of place.</p></pre>MrSaints: <pre><p>Use <a href="https://github.com/golang/lint" rel="nofollow">go lint</a>, and <a href="https://blog.golang.org/go-fmt-your-code" rel="nofollow">go fmt</a>. The former will serve you well when writing documentation. You can even run it <a href="http://go-lint.appspot.com/" rel="nofollow">online</a>. It is based on <a href="https://github.com/golang/go/wiki/CodeReviewComments#comment-sentences" rel="nofollow">CodeReviewComments</a> and <a href="http://golang.org/doc/effective_go.html#commentary" rel="nofollow">Effective Go</a> which you should also check out.</p></pre>Fwippy: <pre><p>Personally? Insufficiently.</p></pre>