Go Concepts - Documentation

Overview

Go generates in-line documentation for symbols in packages, for the standard library and for custom code, as long as it is referred to from GOPATH, via the go doc command.

The Go documentation uses the term command frequently to refer to an executable program - as in command-line application.

Reading Documentation

To read the package summary:

go doc <package-path>
go doc <package-name>

where the package-path is the same string literal used in the import statement.

Example:

go doc fmt
go doc project1/blue

To get the documentation for a package identifier (function name, type, etc):

go doc <package-path> <identifier>

Example:

go doc fmt Println
go doc project1/blue Blue

Writing Documentation

Package-Level Documentation

To add a large body of text to document a package, include a file called doc.go in the package directory. Place the package documentation as a comment before the package declaration:

/*
   ...
   ...
*/
pakcage mypackage

This documentation will be shown before any type or function documentation is displayed for the package.

TODO not testes. Test and annotate.

Package Identifier Documentation

Add a "//" comment before the exported identifier (package, function, type and global variable).

Example:

// This function pains all its arguments blue
fun Blue(s string) string {
...
}

go doc will work as follows:

go doc blue Blue
func Blue(s string) string
    This function paints all its arguments blue

Local Web Site

godoc -http=":8088"

The documentation is available at http://localhost:8088/pkg