github.com/xushiwei/go@v0.0.0-20130601165731-2b9d83f45bc9/doc/articles/godoc_documenting_go_code.html

<!--{
"Title": "Godoc: documenting Go code",
"Template": true
}-->

<p>
The Go project takes documentation seriously. Documentation is a huge part of
making software accessible and maintainable. Of course it must be well-written
and accurate, but it also must be easy to write and to maintain. Ideally, it
should be coupled to the code itself so the documentation evolves along with the
code. The easier it is for programmers to produce good documentation, the better
for everyone.
</p>

<p>
To that end, we have developed the <a href="/cmd/godoc/">godoc</a> documentation
tool. This article describes godoc's approach to documentation, and explains how
you can use our conventions and tools to write good documentation for your own
projects.
</p>

<p>
Godoc parses Go source code - including comments - and produces documentation as
HTML or plain text. The end result is documentation tightly coupled with the
code it documents. For example, through godoc's web interface you can navigate
from a function's <a href="/pkg/strings/#HasPrefix">documentation</a> to its
<a href="/src/pkg/strings/strings.go?#L312">implementation</a> with one click.
</p>

<p>
Godoc is conceptually related to Python's
<a href="http://www.python.org/dev/peps/pep-0257/">Docstring</a> and Java's
<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html">Javadoc</a>,
but its design is simpler. The comments read by godoc are not language
constructs (as with Docstring) nor must they have their own machine-readable
syntax (as with Javadoc). Godoc comments are just good comments, the sort you
would want to read even if godoc didn't exist.
</p>

<p>
The convention is simple: to document a type, variable, constant, function, or
even a package, write a regular comment directly preceding its declaration, with
no intervening blank line. Godoc will then present that comment as text
alongside the item it documents. For example, this is the documentation for the
<code>fmt</code> package's <a href="/pkg/fmt/#Fprint"><code>Fprint</code></a>
function:
</p>

{{code "/src/pkg/fmt/print.go" `/Fprint formats using the default/` `/func Fprint/`}}

<p>
Notice this comment is a complete sentence that begins with the name of the
element it describes. This important convention allows us to generate
documentation in a variety of formats, from plain text to HTML to UNIX man
pages, and makes it read better when tools truncate it for brevity, such as when
they extract the first line or sentence.
</p>

<p>
Comments on package declarations should provide general package documentation.
These comments can be short, like the <a href="/pkg/sort/"><code>sort</code></a>
package's brief description:
</p>

{{code "/src/pkg/sort/sort.go" `/Package sort provides/` `/package sort/`}}

<p>
They can also be detailed like the <a href="/pkg/encoding/gob/"><code>gob</code></a>
package's overview. That package uses another convention for packages
that need large amounts of introductory documentation: the package comment is
placed in its own file, <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, which
contains only those comments and a package clause.
</p>

<p>
When writing package comments of any size, keep in mind that their first
sentence will appear in godoc's <a href="/pkg/">package list</a>.
</p>

<p>
Comments that are not adjacent to a top-level declaration are omitted from
godoc's output, with one notable exception. Top-level comments that begin with
the word <code>"BUG(who)"</code> are recognized as known bugs, and included in
the "Bugs" section of the package documentation. The "who" part should be the
user name of someone who could provide more information. For example, this is a
known issue from the <a href="/pkg/sync/atomic/#pkg-note-BUG"><code>sync/atomic</code></a> package:
</p>

<pre>
// BUG(rsc): On x86-32, the 64-bit functions use instructions
// unavailable before the Pentium MMX. On both ARM and x86-32, it is the
// caller's responsibility to arrange for 64-bit alignment of 64-bit
// words accessed atomically.
</pre>

<p>
Godoc treats executable commands in the same way. It looks for a comment on
package main, which is sometimes put in a separate file called <code>doc.go</code>.
For example, see the
<a href="/cmd/godoc/">godoc documentation</a> and its corresponding
<a href="/src/cmd/godoc/doc.go">doc.go</a> file.
</p>

<p>
There are a few formatting rules that Godoc uses when converting comments to
HTML:
</p>

<ul>
<li>
Subsequent lines of text are considered part of the same paragraph; you must
leave a blank line to separate paragraphs.
</li>
<li>
Pre-formatted text must be indented relative to the surrounding comment text
(see gob's <a href="/src/pkg/encoding/gob/doc.go">doc.go</a> for an example).
</li>
<li>
URLs will be converted to HTML links; no special markup is necessary.
</li>
</ul>

<p>
Note that none of these rules requires you to do anything out of the ordinary.
</p>

<p>
In fact, the best thing about godoc's minimal approach is how easy it is to use.
As a result, a lot of Go code, including all of the standard library, already
follows the conventions.
</p>

<p>
Your own code can present good documentation just by having comments as
described above. Any Go packages installed inside <code>$GOROOT/src/pkg</code>
and any <code>GOPATH</code> work spaces will already be accessible via godoc's
command-line and HTTP interfaces, and you can specify additional paths for
indexing via the <code>-path</code> flag or just by running <code>"godoc ."</code>
in the source directory. See the <a href="/cmd/godoc/">godoc documentation</a>
for more details.
</p>

<p>
Godoc recognizes example functions written according to the
<a href="/pkg/testing/#pkg-overview"><code>testing</code></a> package's naming
conventions and presents them appropriately.
</p>