Skip to content
Snippets Groups Projects
godoc_documenting_go_code.html 5.43 KiB
Newer Older
  • Learn to ignore specific revisions
  • <!--{
    "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/">gob package</a>'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/bytes/#bugs">bytes package</a>:
    </p>
    
    <pre>
    // BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
    </pre>
    
    <p>
    Godoc treats executable commands somewhat differently. Instead of inspecting the
    command source code, it looks for a Go source file belonging to the special
    package "documentation”. The comment on the "package documentation” clause is
    used as the command's documentation. 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>