From 235863cb128bbc00a659ed7446e42cb810cbaa46 Mon Sep 17 00:00:00 2001 From: Francisco Souza Date: Thu, 15 Mar 2012 14:51:44 +1100 Subject: [PATCH] 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 --- doc/Makefile | 1 + doc/articles/godoc_documenting_go_code.html | 139 ++++++++++++++++++++ doc/docs.html | 2 +- doc/reference.html | 2 +- misc/dashboard/godashboard/package.html | 2 +- src/cmd/godoc/doc.go | 2 +- 6 files changed, 144 insertions(+), 4 deletions(-) create mode 100644 doc/articles/godoc_documenting_go_code.html diff --git a/doc/Makefile b/doc/Makefile index 687f1b1eb5..f4e0593d4a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,6 +9,7 @@ RAWHTML=\ articles/laws_of_reflection.rawhtml\ articles/c_go_cgo.rawhtml\ articles/go_concurrency_patterns_timing_out_moving_on.rawhtml\ + articles/godoc_documenting_go_code.rawhtml\ articles/image_draw.rawhtml\ effective_go.rawhtml\ go1.rawhtml\ diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html new file mode 100644 index 0000000000..ca66076ad7 --- /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. +

diff --git a/doc/docs.html b/doc/docs.html index 39e4573eb6..30e237d44a 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -124,7 +124,7 @@ Guided tours of Go programs. diff --git a/doc/reference.html b/doc/reference.html index 37c3418f54..6d78d3bc0e 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -64,7 +64,7 @@ Using GDB to debug Go programs.
  • C? Go? Cgo! - linking against C code with cgo.
  • Defer, Panic, and Recover
  • Go Slices: usage and internals
    • -
  • Godoc: documenting Go code - writing good documentation for godoc.
    • +
  • Godoc: documenting Go code - writing good documentation for godoc.
  • Profiling Go Programs
    • diff --git a/misc/dashboard/godashboard/package.html b/misc/dashboard/godashboard/package.html index b688af9e2b..e792162cfc 100644 --- a/misc/dashboard/godashboard/package.html +++ b/misc/dashboard/godashboard/package.html @@ -31,7 +31,7 @@

    The info column shows the first paragraph from the - package doc comment. + package doc comment.

    Most Installed Packages (this week)

    diff --git a/src/cmd/godoc/doc.go b/src/cmd/godoc/doc.go index 1a6471c76f..39ecc6e63a 100644 --- a/src/cmd/godoc/doc.go +++ b/src/cmd/godoc/doc.go @@ -138,7 +138,7 @@ one may run godoc as follows: godoc -http=:6060 -zip=go.zip -goroot=$HOME/go 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 -- 2.48.1