Go Standard command detailed 0.5 godoc

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

transported from GitHub Herring go_command_tutorial, absolutely dry, thanks to the author.

The command godoc is a powerful tool for displaying the documentation for the specified code package. We can go get code.google.com/p/go.tools/cmd/godoc install it by running it.

The command has two modes to choose from. If you do not add a tag when you execute the command -http , the command runs in command-line mode. When you print a document in plain text format to standard output, the command execution is finished. For example, we use the command-line mode to view the documentation of the code package FMT:

hc@ubt:~$ godoc fmt

For space reasons, we omitted the results of the document query in this section. Readers can run the above command on their own. After the command is executed, we can see the contents of the neatly organized document. This includes fmt a review of the code package and declarations, documentation, and examples of all exportable members.

Sometimes we just want to see a document of a function or struct type, then we can add the name of the function or struct to the last side of the command, like this:

hc@ubt:~$ Printf

Or:

hc@ubt:~$ File

If we want to see a document of several functions in a code package at the same time, simply append the function or struct name to the command. For example, we want to look fmt Printf Println at the documentation for functions and functions in the code package:

hc@ubt:~$ PrintfPrintln

If we want not only to see the declarations of exportable members in the document, but also to see their source code, we can godoc add tags when executing the command -src , such as:

hc@ubt:~$ Printf

The go language sets up proprietary rules for programs that use the sample code. We are not here to discuss the details of this rule. Just know that because of this proprietary rule, godoc commands can extract the sample code according to these rules and add them to the corresponding document. If we want to see the net sample code about it while looking at the document of the struct in the code package Listener , we just need to add the tag when we execute the command -ex . Here's how to use it:

hc@ubt:~$ Listener

In the actual go locale, we may encounter a case where the command source file produces an executable file with the same name as the code package. For example, this section describes the commands go and the official code package go . Now we have to tell the godoc command explicitly. To see the documentation for the executable go, we need to prefix the name with "cmd/":

hc@ubt:~$ godoc cmd/go

In addition, if we want to see the HTML-formatted document, we need to add tags -html . Of course, viewing in command-line mode is a poor result. However, if you look closely, you can find some of the corresponding source code link address.

In general, the godoc command will go to the Go Language root directory and the environment variable Gopath value (one or more workspaces) to find the code package in the workspace directory. However, we can also -goroot create a Go language root directory by adding tags. This specified go language root is only used for the execution of the secondary command. Examples are as follows:

hc@ubt:~$ godoc -goroot="/usr/local/go" fmt

Now let's take a look at another pattern. If we add a tag while executing -http a command, another mode is enabled. This mode is called the Web server mode, which provides the go language document as a Web page.

We use the following command to start the document Web server:

hc@ubt:~/golang/goc2p$ godoc -http=:6060

The -http value of the token :6060 indicates that the starting Web server uses the native 6060 port. After that, we can view the go document as a Web page by entering http://localhost:6060 in the address bar of the Web browser.

Figure 0-1 Native Go document Web service Home

This is the same as the Web Service page of the official go language site. This allows us to view the Go language documentation without the convenience of accessing the official go language site. And, more conveniently, through the native Go Document Web service, we can also view the documentation for all the code under the native workspace. For example, the page for the code package in the GOC2P project, pkgtool such as:

Figure 0-2 The Go document page of the Pkgtool package in the GOC2P project

Now, we are starting the Go Document Web server on this machine with Port 9090. The command is as follows:

hc@ubt:~$ godoc -http=:9090 -index

Note that to use the -index tag to open the search index, the index is created and maintained when the server is started. Otherwise, submitting a query in a Web page or command-line terminal will return an error "Search index Disabled:no results available".

Identifiers and full-text search information are provided in the index (which is supported by regular expressions for the searchable nature). Full-Text search results show that the maximum number of entries can be provided by tags -maxresults . -maxresultsthe tag default value is 10000. If you do not want to provide so many result entries, you can set a smaller value. Even if you do not want to provide full-text search results, you can -maxresults set the value of the tag to 0 so that the server creates an identifier index only and does not create a full-text search index at all. An identifier index is an index of the names of program entities (variables, constants, functions, structs, and interfaces).

Because the -index document server creates an index at startup when the tag is used, the search service is not available immediately after the document server is started, and it takes a moment. Before the index is created, our search operation will be prompted with the message "Indexing in Progress:result might be inaccurate".

If we godoc start the Go Document Web server with a command on this machine and the IP address is 192.168.1.4 and the port is 9090, then we can query through the following command on another command-line terminal or even another computer that can connect to the local machine. The query commands are as follows:

hc@ubt:~$ godoc -q -server="192.168.1.4:9090"Listener

At the end of the command is the content to query, which can be any string you want to search for, not just the name of a code package, function, or struct.

Marks -q the ability to turn on remote queries. The tag -server="192.168.1.4:9090" indicates the IP address and port number of the remote document server. In fact, if you do not specify the address of the remote query server, the command will Self-address ": 6060" and "golang.org" as the address of the remote query server. These two addresses are the default native document Web site address and the Official document Web site address. So we can also query the standard library information by executing the following command:

hc@ubt:~$ godoc -q=true fmt

Commands godoc also have many tokens available, but they are not commonly used in common situations. If the reader is interested, you can perform a view in the command line environment godoc .

As for how to write good Code pack documentation file, I in the "Go concurrent programming Combat" in section 5.2 of the detailed description.