"Translation" Godoc: Document GO Code

This is a creation in Article, where the information may have evolved or changed.

Children's shoes, April Fools ' Day good! Because I am stupid, can not live this high-end festival, so there is no holiday.
So today there will be no change to the name of Mikeghost news, there will be no such as running IOS app on Android message appears, of course, we do not need to cross the Muyora read this article.
Life has to go on ...
The original "Godoc:documenting Go code" in this: http://blog.golang.org/2011/03/godoc-documenting-go-code.html
—————-Translation Split Line —————-

The Go project treats the document with a serious attitude. Documentation is an important part of making software easy to handle and maintain. Of course, it must be well written and accurate, and it must be easy to write and maintain. Ideally, it should be associated with the code so that the document can be updated with the code. The easier it is for programmers to build good documents, the more benefits to everyone.

In the end, we developed the Godoc documentation tool. This article explains how to generate documents with Godoc and explains how to use our conventions and tools to write good documentation in your own projects.

Godoc parses the Go code, including comments, and then generates documents such as HTML or plain text. This makes the document tightly coupled with the code it describes. For example, through the Godoc Web interface you can jump from a function's document to its implementation by tapping it.

The Godoc concept is similar to Python's docstring and Java Javadoc, but is simpler to design. Comments that Godoc read should not be language constructs (such as docstring) or must have some machine-recognized markup (such as Javadoc). Godoc annotations are good annotations, even in the absence of Godoc, and are short and easy to read.

The convention is simple: comment on a type, variable, constant, function, or package, write a plain comment before it is defined, and do not insert a blank line. Godoc will recognize these annotations as documents for subsequent content. For example, this is the document for the FMT package Fprint function (this part is not translated, it's a bit of flavor):

Fprint formats using the default formats for it operands and writes to w.//Spaces is added between operands when Nei Ther is a string.//It returns the number of bytes written and any write error encountered.func fprint (w io. Writer, a ... interface{}) (n int, error OS. Error) {

Note that these comments are all ordinary sentences with the names of the elements they describe. This important convention allows us to generate documents in a variety of formats, from plain text to HTML, or to the man Manual of UNIX, or to truncate it for easier readability, such as displaying only the first line or the first sentence.

The comments on the package provide a document about the package's approximate information. This comment can be short, such as a short description of the sort package:

The sort package provides primitives for sorting arrays//and user-defined collections.package sort

You can also use a detailed description like the GOB package. This package requires a lot of introductory documentation, and other conventions are used: The package's comments in its Doc.go file contain comments and the terms of use of the package.

Regardless of the size of the comment, remember that the first sentence will appear in the Godoc package list.

Annotations that are not adjacent to the top-level definition are ignored by the output of the Godoc, but there is an unexpected. Top-level comments that start with "bug" are identified as known bugs and are included in the "Bugs" section of the package document. "Who" should be the name of the user who can provide further 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 is somewhat different as an executable command. It does not check the specified source code, but in the special package belonging to Go source "documentation" to look for. The "package documentation" comment as the command document. For example, view the Godoc documentation and its corresponding doc.go file.

When converting annotations to HTML with Godoc, there are some formatting rules:

• Immediately after the next line of text is considered to be the same paragraph; you must empty a line to separate the paragraphs.
• The pre-formatted text must be indented within the annotation symbol (read Gob's doc.go as an example).
• Unordered extra symbols, URLs are converted to HTML links.

Note that none of these rules requires you to do anything beyond what you normally do.

In fact, the best part of Godoc is its ease of use. As a result, many Go codes, including many standard libraries, have been followed by these conventions.

The

can generate a good document from the comments in your own code, as described above. Any Go package installed in $GOROOT/src/pkg/ can already be accessed through the Godoc command line and HTTP interface, or you can either add the specified path through the-path identity, or execute " godoc" in the source code directory. ". Read Godoc documentation for more details.