diff options
Diffstat (limited to 'doc/articles/godoc_documenting_go_code.html')
-rw-r--r-- | doc/articles/godoc_documenting_go_code.html | 147 |
1 files changed, 0 insertions, 147 deletions
diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html deleted file mode 100644 index 3f4e3228c..000000000 --- a/doc/articles/godoc_documenting_go_code.html +++ /dev/null @@ -1,147 +0,0 @@ -<!--{ -"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> |