Welcome to official account No. DailyOps

I wish you a happy 2022 new year in advance~
Original text connection golang notes and documentation and go doc/godoc notes

golang comments

• Single-Line Comments

It is the most common and used annotation method, starting with / / and followed by comments.

It can be a single line or after a statement.

For example:

package main

// We need to import packages, and only import what we need. Redundant import will cause compilation errors
import (
    "fmt"  // Here is also a single line comment, followed by a statement
)

• multiline comment

It is not often used. It is generally used for code block comments or package document description. Document description needs to describe the package and its exposed functions in detail as much as possible. Sometimes single line comments are inconvenient to use

For example:

package convert

import (
	"strconv"
)

/*
 * Here are multi line comments for detailed description of external functions in the user-defined package
 * The description can be as detailed as possible so that everyone can understand its function
 */

func Convert(name string) (string) {
    ... ...
}

golang document description

During project development, code comments are essential, but for go, customize the package and its exposed functions, and add additional special instructions to facilitate users to quickly understand and use.

This special description is the document description, and the writing is required to be standardized

• Package description

  Generally, the description starts with package in the line immediately above the package keyword, such as

  // Package convert is ...
  package convert
  

• Function description

  The Function description is in the line immediately above func SomeName(). It is generally recommended to start with Function, such as

  // Function SomeName is uesd to ...
  func SomeName() {
      ... ...
  }
  

go doc tool

The go doc command is based on the go command. The main function is to print out the document information of the Go program, which is the document description we mentioned above.

You can view the usage of specific commands through go help sub command, such as go help doc here

In actual use, go doc is very useful when it is unclear how the third party uses it, such as string to floating point,

• go doc strconv

  Directly followed by the package name, you can view the externally exposed methods and variables in the package

• go doc strconv ParseFloat

  The package name followed by the corresponding method name and variable name can be used to view the specific description and usage

  # go doc strconv ParseFloat
  package strconv // import "strconv"
  
  func ParseFloat(s string, bitSize int) (float64, error)
      ParseFloat converts the string s to a floating-point number with the
      precision specified by bitSize: 32 for float32, or 64 for float64. When
      bitSize=32, the result still has type float64, but it will be convertible to
      ... ...
  

  Another example (note that package.method or package method can be used)

  # go doc fmt.Sprintf
  package fmt // import "fmt"
  
  func Sprintf(format string, a ...interface{}) string
      Sprintf formats according to a format specifier and returns the resulting
      string.
  

• No parameters are added after go doc

  The document of the code package represented by the current directory and the list of package level program entities in it will be printed

go doc parameter description

• -c case sensitive letters in parameters
• -u at the same time, non exportable program entities will be printed. By default, only exportable entities will be printed (the principle of whether golang can be called by other packages is exportable, with the initial capital)
• -cmd prints the exportable program entities in the main package at the same time
• -short no entity document is identified by a line

godoc and go doc are confused

godoc is very similar to go doc, but different~

• go doc is a subcommand of go. It is used to output the document description of related entities on the command line

• godoc starts a web program locally and displays the document information of local related packages through a browser, similar to the online documents of golang

• godoc is not installed by default. You can install it through the following command. By default, it is installed into the directory defined by the GOBIN environment variable

go get -v -u golang.org/x/tools/cmd/godoc

Enable local web access to online documents

godoc -http=:8080

Then enter in the browser http://localhost:8080 You can view it