mirror of
https://github.com/golang/go
synced 2024-11-21 20:14:52 -07:00
doc: add "Godoc: documenting Go code" article
Originally published on The Go Programming Language Blog, March 31, 2011. http://blog.golang.org/2011/03/godoc-documenting-go-code.html R=golang-dev, adg CC=golang-dev https://golang.org/cl/5830043
This commit is contained in:
parent
1c224ab9dd
commit
235863cb12
@ -9,6 +9,7 @@ RAWHTML=\
|
|||||||
articles/laws_of_reflection.rawhtml\
|
articles/laws_of_reflection.rawhtml\
|
||||||
articles/c_go_cgo.rawhtml\
|
articles/c_go_cgo.rawhtml\
|
||||||
articles/go_concurrency_patterns_timing_out_moving_on.rawhtml\
|
articles/go_concurrency_patterns_timing_out_moving_on.rawhtml\
|
||||||
|
articles/godoc_documenting_go_code.rawhtml\
|
||||||
articles/image_draw.rawhtml\
|
articles/image_draw.rawhtml\
|
||||||
effective_go.rawhtml\
|
effective_go.rawhtml\
|
||||||
go1.rawhtml\
|
go1.rawhtml\
|
||||||
|
139
doc/articles/godoc_documenting_go_code.html
Normal file
139
doc/articles/godoc_documenting_go_code.html
Normal file
@ -0,0 +1,139 @@
|
|||||||
|
<!--{
|
||||||
|
"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>
|
@ -124,7 +124,7 @@ Guided tours of Go programs.
|
|||||||
<ul>
|
<ul>
|
||||||
<li><a href="/doc/articles/go_command.html">About the Go command</a> - why we wrote it, what it is, what it's not, and how to use it.</li>
|
<li><a href="/doc/articles/go_command.html">About the Go command</a> - why we wrote it, what it is, what it's not, and how to use it.</li>
|
||||||
<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
|
<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
|
||||||
<li><a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
|
<li><a href="/doc/articles/godoc_documenting_go_code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
|
||||||
<li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
|
<li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
@ -64,7 +64,7 @@ Using GDB to debug Go programs.
|
|||||||
<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
|
<li><a href="/doc/articles/c_go_cgo.html">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
|
||||||
<li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li>
|
<li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li>
|
||||||
<li><a href="/doc/articles/slices_usage_and_internals.html">Go Slices: usage and internals</a></li>
|
<li><a href="/doc/articles/slices_usage_and_internals.html">Go Slices: usage and internals</a></li>
|
||||||
<li><a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
|
<li><a href="/doc/articles/godoc_documenting_go_code.html">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
|
||||||
<li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
|
<li><a href="http://blog.golang.org/2011/06/profiling-go-programs.html">Profiling Go Programs</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
@ -31,7 +31,7 @@
|
|||||||
|
|
||||||
<p>
|
<p>
|
||||||
The <b>info</b> column shows the first paragraph from the
|
The <b>info</b> column shows the first paragraph from the
|
||||||
<a href="http://blog.golang.org/2011/03/godoc-documenting-go-code.html">package doc comment</a>.
|
<a href="http://golang.org/doc/articles/godoc_documenting_go_code.html">package doc comment</a>.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h2>Most Installed Packages (this week)</h2>
|
<h2>Most Installed Packages (this week)</h2>
|
||||||
|
@ -138,7 +138,7 @@ one may run godoc as follows:
|
|||||||
godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
|
godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
|
||||||
|
|
||||||
See "Godoc: documenting Go code" for how to write good comments for godoc:
|
See "Godoc: documenting Go code" for how to write good comments for godoc:
|
||||||
http://blog.golang.org/2011/03/godoc-documenting-go-code.html
|
http://golang.org/doc/articles/godoc_documenting_go_code.html
|
||||||
|
|
||||||
*/
|
*/
|
||||||
package documentation
|
package documentation
|
||||||
|
Loading…
Reference in New Issue
Block a user