+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. +
+ ++To that end, we have developed the godoc 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. +
+ ++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 documentation to its +implementation with one click. +
+ ++Godoc is conceptually related to Python's +Docstring and Java's +Javadoc, +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. +
+ +
+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
+fmt package's Fprint
+function:
+
+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. +
+ +
+Comments on package declarations should provide general package documentation.
+These comments can be short, like the sort
+package's brief description:
+
+They can also be detailed like the gob 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, doc.go, which +contains only those comments and a package clause. +
+ ++When writing package comments of any size, keep in mind that their first +sentence will appear in godoc's package list. +
+ +
+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 "BUG(who)” 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 bytes package:
+
+// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly. ++ +
+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 +godoc documentation and its corresponding +doc.go file. +
+ ++There are a few formatting rules that Godoc uses when converting comments to +HTML: +
+ ++Note that none of these rules requires you to do anything out of the ordinary. +
+ ++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. +
+ +
+Your own code can present good documentation just by having comments as
+described above. Any Go packages installed inside $GOROOT/src/pkg
+and any GOPATH work spaces will already be accessible via godoc's
+command-line and HTTP interfaces, and you can specify additional paths for
+indexing via the -path flag or just by running "godoc ."
+in the source directory. See the godoc documentation
+for more details.
+
The info column shows the first paragraph from the - package doc comment. + package doc comment.