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 public flysnow_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 with go doc commands 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 the godoc command 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 use go doc of commands is a good choice.

123456789101112131415161718

➜hello go help docusage:go doc [-u] [-c] [package|[ Package.] Symbol[.method]]doc prints the documentation comments associated with the item identified by Itsarguments (a package, cons T, func, type , Var, or method) followed by a one-linesummary of each of the First-level item S "under" that item (package-leveldeclarations for a package , methods for a type , etc.). Flags:-crespect case when matching symbols.-cmdtreat a command The (package main) is a regular package. Otherwise Package Main ' s exported symbols is hidden when showing the package ' s top-level docu Mentation.-ushow documentation for unexported as well as Exportedsymbols and methods.

From the above can be seen, go doc the 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.

12345678910

/ * commonly used libraries, there are some common methods to facilitate the use of */package lib//an addition implementation //return value of A+b func ADDint)int {return a+b}

123456

➜ "Flysnow.org/hello/lib" provides a common library, there are some common methods, convenient to use the Func Add (a, b int) int

Executes in the current directory go 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.

12345678910111213141516171819202122232425262728293031323334

➜lib Go Doc jsonpackage JSON//import"Encoding/json"Package JSON implements encoding and decoding of JSON as definedinchRFC4627. The mapping between JSON and Go values is describedinchThedocumentation forThe Marshal and Unmarshal functions. See"JSON and Go" forAn introduction to this Package:https://golang.org/doc/articles/json_and_go.htmlfunc Compact (DST *bytes. Buffer, SRC []byte] errorfunc htmlescape (DST *bytes. Buffer, SRC []byte] func Indent (DST *bytes. Buffer, src []byte, prefix, indent string) Errorfunc Marshal (v interface{}) ([]byte, error) func marshalindent (v interface{ }, prefix, indent string) ([]byte, error) func unmarshal (data []byte, v interface{}) errortypeDecoder struct{...} Func newdecoder (R io. Reader) *decodertypeDelim RunetypeEncoder struct{...} Func newencoder (w io. Writer) *encodertypeInvalidutf8error struct{...}typeInvalidunmarshalerror struct{...}typeMarshaler interface{...}typeMarshalererror struct{...}typeNumber stringtypeRawmessage []bytetypeSyntaxError struct{...}typeToken interface{}typeUnmarshalfielderror struct{...}typeUnmarshaltypeerror struct{...}typeUnmarshaler interface{...}typeUnsupportedtypeerror struct{...}typeUnsupportedvalueerror struct{...}

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

123456789101112131415

➜ "Encoding/json"type Decoder struct {//have unexported fields.} A Decoder reads and decodes JSON values from an input Stream.func Newdecoder (r io. Reader) *decoderfunc (Dec *decoder) Buffered () Io. Readerfunc (Dec *decoder) Decode (v interface{}) errorfunc (Dec *decoder) More () Boolfunc (Dec *decoder) token () (token, ER ROR) func (Dec *decoder) Usenumber ()

Now we see this Decoder there are many ways to further review the documentation for these methods, for example Decode .

1234567

➜ Lib Go doc json. Decoder.decode func (Dec *decoder) Decode (v interface{}) error in the value pointed to by V. for for details on 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, so godoc you can use it.

1	➜ 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 the http://127.0.0.1:6060 access, 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 documents http://127.0.0.1:6060/pkg/ Will not be the same as the official website, you start the service, is based on your computer GOROOT and the GOPATH two 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.

12345678910

/ * commonly used libraries, there are some common methods to facilitate the use of */package lib//an addition implementation //return value of A+b func ADDint)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 we go doc godoc can 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 name example_test.go .
2. In this go file, define a Example function 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.

12345678910

Package libimport"FMT"funcExample() {Sum:=add (1,2) fmt. Println ("1+2=", sum)//output://1+2=3}

This is the Add sample code for the function that we just wrote, and we godoc can see the results as we run.

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 public flysnow_org , the first time to see follow-up notes.