Go Language Practical Notes (iii) | Go DOC Documentation

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

"Go language Combat" reading notes, not to be continued, welcome attention to the publicflysnow_org, the first time to see follow-up notes.

For collaborative development or code sharing, a document is a tutorial that can help developers quickly understand and use the code, the more comprehensive the document, the more detailed, the faster the entry, and the higher the efficiency.

In the go language, go gives us the tools to quickly generate documents and view documents so that we can easily write and view documents.

Go provides two ways to view documents, one for use withgo doccommands at the terminal, and for those who develop with tools such as Vim, without leaving the terminal, to view the documents they want to see, and to encode them.

The second way is to use the browser to view the way, through thegodoccommand can start a Web service in the local, we can open a browser, access to this service to view our go document.

Viewing a document from a terminal

This method is suitable for development at the terminal, they generally do not like leaving the terminal, check out can continue to encode, the usego docof commands is a good choice.

➜  hello go help doc
usage: go doc [-u] [-c] [package|[package.]symbol[.method]]

Doc prints the documentation comments associated with the item identified by its
arguments (a package, const, func, type, var, or method) followed by a one-line
summary of each of the first-level items "under" that item (package-level
declarations for a package, methods for a type, etc.).

Flags:
    -c
        Respect case when matching symbols.
    -cmd
        Treat a command (package main) like a regular package.
        Otherwise package main's exported symbols are hidden
        when showing the package's top-level documentation.
    -u
        Show documentation for unexported as well as exported
        symbols and methods.

From the above can be seen,go docthe use of relatively simple, received the parameter is the package name, or in the package structure, methods and so on. If we do not enter any parameters, then the current directory is displayed in the document, see an example below.

/ *
  Common libraries provided, there are some common methods, easy to use
  * /
package lib

// an addition implementation
// return the value of a + b
func Add (a, b int) int {
     return a + b
}
➜ lib go doc
package lib // import "flysnow.org/hello/lib"

Common libraries provided, there are some common methods, easy to use

func Add (a, b int) int

Executes in the current directorygo doc, outputting the document information in the current directory.

In addition, we can specify a package that lists information about the current package, including documents, methods, structures, and so on.

➜  lib go doc json
package json // import "encoding/json"

Package json implements encoding and decoding of JSON as defined in RFC
4627. The mapping between JSON and Go values is described in the
documentation for the Marshal and Unmarshal functions.

See "JSON and Go" for an introduction to this package:
https://golang.org/doc/articles/json_and_go.html

func Compact(dst *bytes.Buffer, src []byte) error
func HTMLEscape(dst *bytes.Buffer, src []byte)
func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
func Marshal(v interface{}) ([]byte, error)
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
func Unmarshal(data []byte, v interface{}) error
type Decoder struct{ ... }
    func NewDecoder(r io.Reader) *Decoder
type Delim rune
type Encoder struct{ ... }
    func NewEncoder(w io.Writer) *Encoder
type InvalidUTF8Error struct{ ... }
type InvalidUnmarshalError struct{ ... }
type Marshaler interface{ ... }
type MarshalerError struct{ ... }
type Number string
type RawMessage []byte
type SyntaxError struct{ ... }
type Token interface{}
type UnmarshalFieldError struct{ ... }
type UnmarshalTypeError struct{ ... }
type Unmarshaler interface{ ... }
type UnsupportedTypeError struct{ ... }
type UnsupportedValueError struct{ ... }

The above is ajsonpackage for example, we look at the document of the package, from which we can see that it has aDecoderstruct named, and we look further at the structure of the document.

➜  lib go doc json.Decoder
package json // import "encoding/json"

type Decoder struct {
    // Has unexported fields.
}
    A Decoder reads and decodes JSON values from an input stream.


func NewDecoder(r io.Reader) *Decoder
func (dec *Decoder) Buffered() io.Reader
func (dec *Decoder) Decode(v interface{}) error
func (dec *Decoder) More() bool
func (dec *Decoder) Token() (Token, error)
func (dec *Decoder) UseNumber()

Now we see thisDecoderthere are many ways to further review the documentation for these methods, for exampleDecode.

➜  lib go doc json.Decoder.Decode    
func (dec *Decoder) Decode(v interface{}) error
    Decode reads the next JSON-encoded value from its input and stores it in the
    value pointed to by v.

    See the documentation for Unmarshal for details about the conversion of JSON
    into a Go value.

go docThis is the way to do it, step through it, narrow it down, and see the documentation for the packages, structs, interfaces, or function methods you want to see.

Browse Documents Online

go docTerminal view of the way, although very convenient, but not high efficiency, and do not see the details and jump, this go for us to provide a browser-based Web page way to browse the API documentation, we only use a few mouse, you can view, but also in the method, package and other jumps between, more concise and convenient.

To start a Web Online API documentation service is simple, sogodocyou can use it.

➜  lib godoc -http=:6060

After the HTTP is to specify the Web service to listen to the IP and port, after running, we can open the browser, enter thehttp://127.0.0.1:6060access, you will find the open page, and Golang's official website, yes, this is actually a copy of the official site, but the package of documentshttp://127.0.0.1:6060/pkg/Will not be the same as the official website, you start the service, is based on your computerGOROOTand theGOPATHtwo paths under all the package generated documents, will be more than the official website is only standard library documents.

Online Browsing API documentation is very convenient, just need mouse click on it, you can click on the blue hyperlink in the method, structure, interface and package, etc., can also view the corresponding source code, sample code, very convenient, we often use this online browsing method.

Build Your own documents

Go Documentation tool, there is also a bright spot, is to support the developer to write their own code, as long as the developer according to certain rules, you can automatically generate documents.

In our code, the document is a comment, and the go language uses the same annotation style as C and Java. One is a double slash way, one is a slash and an asterisk.

/ *
  Common libraries provided, there are some common methods, easy to use
  * /
package lib

// an addition implementation
// return the value of a + b
func Add (a, b int) int {
     return a + b
}

This is also the example of the Chinese document written in two styles. If you want to Fuzhou a car document for which identity, add it to your code just before the identifier, using comments.

Now wego docgodoccan see the document we just commented on, whether we're using it or not.

Add a document Example

We are looking at a lot of official API documentation, we can see some examples in the document, these examples will tell us how to use the API, and this example printed output is what, I think this is very good, so look at the function document does not understand, can refer to this example, then for our own writing API, How do I add sample code to an API document?

Here I refer to the official source code, summed up the test a bit, found feasible, here to share.

1. The sample code must be stored separately in a file with the file nameexample_test.go.
2. In this go file, define aExamplefunction with the name, the argument is empty
3. The output of the example takes the following way, starting with//output: one row, and one row for each line of output.

Having said these three rules, the following is an example of a more intuitive understanding.

package lib

import "fmt"

func Example() {
    sum:=Add(1,2)
    fmt.Println("1+2=",sum)
    //Output:
    //1+2=3
}

This is theAddsample code for the function that we just wrote, and wegodoccan see the results as we run.

Sample code Documentation

Go documentation tool is very powerful and more features, we can use the help command to view. Here again a good third-party API documentation site, including many of the official go library, can jump directly, related source code, very convenient. https://gowalker.org/

"Go language Combat" reading notes, not to be continued, welcome attention to the publicflysnow_org, the first time to see follow-up notes.