How to use the command 'go doc' (with examples)
The ‘go doc’ command is a tool in the Go programming language that allows users to view documentation for packages and symbols. It can provide information on functions, types, constants, variables, and more. By using the ‘go doc’ command, developers can easily access documentation and understand how to use different elements of the Go language.
Use case 1: Show documentation for the current package
Code:
go doc
Motivation:
When working on a Go project, it is often necessary to refer to the documentation of the current package. By using the ‘go doc’ command without any arguments, developers can quickly access the documentation specific to their current package.
Explanation:
The command ‘go doc’ without any arguments displays the documentation for the current package. It provides information about the package itself, including its name, import path, and any exported symbols such as functions, types, and constants.
Example output:
PACKAGE DOCUMENTATION
package main
import "myproject"
Package myproject is an example package that demonstrates the usage of the 'go doc' command.
FUNCTIONS
func HelloWorld()
HelloWorld prints a friendly greeting message.
TYPES
type Person struct {
Name string
Age int
}
Person represents a person with a name and age.
CONSTANTS
const Pi = 3.14159
Pi is a mathematical constant.
Use case 2: Show package documentation and exported symbols
Code:
go doc encoding/json
Motivation:
Sometimes, it is necessary to explore the documentation for a particular package and understand its exported symbols. The ‘go doc’ command can be used to view the package documentation along with all the exported symbols, including functions, types, constants, and variables.
Explanation:
By providing the package import path as an argument, in this case, ’encoding/json’, the ‘go doc’ command displays the package documentation along with all of its exported symbols.
Example output:
PACKAGE DOCUMENTATION
package json
import "encoding/json"
Package json implements encoding and decoding of JSON as defined in RFC 7159. The mapping between JSON and Go values is described in the documentation for the Marshal and Unmarshal functions.
FUNCTIONS
func Marshal(v interface{}) ([]byte, error)
Marshal returns the JSON encoding of v.
TYPES
type InvalidUnmarshalError string
InvalidUnmarshalError is an error type that represents an invalid argument passed to Unmarshal.
type SyntaxError struct {
Offset int64
...
}
SyntaxError is an error type that represents a JSON syntax error.
CONSTANTS
const (
...
)
...
Use case 3: Show also documentation of symbols
Code:
go doc -all encoding/json
Motivation:
When exploring a package in more detail, it can be helpful to view the documentation for not just the package and its exported symbols, but also the documentation for individual symbols such as functions, types, constants, and variables. The ‘-all’ flag allows the ‘go doc’ command to display the documentation for all symbols.
Explanation:
By using the ‘-all’ flag along with the package import path, in this case, ’encoding/json’, the ‘go doc’ command displays the documentation for all symbols in the package, including unexported symbols.
Example output:
SYMBOL DOCUMENTATION
FUNCTIONS
func Compact(dst *bytes.Buffer, src []byte) error
Compact appends to dst the JSON-encoded src with any insignificant whitespace removed.
func HTMLEscape(dst *bytes.Buffer, src []byte)
HTMLEscape appends to dst the JSON-encoded src, with HTML character references.
...
STRUCTS
type SyntaxError struct {
Offset int64 // byte offset of error
...
}
SyntaxError records a syntax error encountered during JSON decoding.
TYPES
type InvalidUTF8Error int64
InvalidUTF8Error is an error type that represents an invalid UTF-8 encoding.
...
CONSTANTS
...
VARIABLES
var (
...
)
...
Use case 4: Show also sources
Code:
go doc -all -src encoding/json
Motivation:
In addition to the package documentation, exported symbol documentation, and documentation for all symbols, developers may also need to view the source code of a particular symbol. The ‘-src’ flag allows the ‘go doc’ command to display the source code for each symbol, providing further insight into how they are implemented.
Explanation:
By using the ‘-all’ and ‘-src’ flags along with the package import path, in this case, ’encoding/json’, the ‘go doc’ command displays the package documentation, exported symbol documentation, documentation for all symbols, and the source code for each symbol.
Example output:
SOURCE CODE
File json.go
package json
// Marshal returns the JSON encoding of v.
func Marshal(v interface{}) ([]byte, error) {
...
}
...
File syntax.go
package json
type SyntaxError struct {
Offset int64 // byte offset of error
...
}
...
File invalid_utf8.go
package json
// InvalidUTF8Error represents an invalid UTF-8 encoding.
type InvalidUTF8Error int64
...
Use case 5: Show a specific symbol
Code:
go doc -all -src encoding/json.Number
Motivation:
When working with a large package, it can be useful to view the documentation and source code for a specific symbol. By providing the symbol name as an argument, in this case, ’encoding/json.Number’, the ‘go doc’ command displays the documentation and source code for that specific symbol.
Explanation:
By using the ‘-all’, ‘-src’, and symbol name arguments, in this case, ’encoding/json.Number’, the ‘go doc’ command displays the documentation and source code for the specified symbol.
Example output:
SYMBOL DOCUMENTATION
TYPES
type Number string
Number represents a JSON number literal.
It is the implementation for the tokens TokenNumber, TokenNegativeNumber.
SOURCE CODE
File number.go
package json
// Number represents a JSON number literal.
type Number string
...
Conclusion
The ‘go doc’ command is a powerful tool that allows developers to quickly access documentation for different packages and symbols in the Go programming language. By utilizing the various flags and arguments, developers can explore package documentation, exported symbols, and source code, making it easier to understand and utilize the Go language effectively.
