From 519725bb3c075ee2462c929f5997cb068e18466a Mon Sep 17 00:00:00 2001 From: Ondřej Surý Date: Mon, 26 Mar 2012 16:50:58 +0200 Subject: Imported Upstream version 2012.03.22 --- doc/articles/godoc_documenting_go_code.html | 139 ++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 doc/articles/godoc_documenting_go_code.html (limited to 'doc/articles/godoc_documenting_go_code.html') diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html new file mode 100644 index 000000000..ca66076ad --- /dev/null +++ b/doc/articles/godoc_documenting_go_code.html @@ -0,0 +1,139 @@ + + +

+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: +

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

+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: +

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

+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. +

-- cgit v1.2.3