More free Golang knowledge, welcome to join Go Baodian | GOLANG ROADMAP
Invitation code: Gopher-1035-0722

Go language supports C-style block annotation / * * / and C + + style line annotation / /. Line comments are more commonly used, while block comments are mainly used as package comments. Of course, they can also be used when a large piece of code is disabled.

Godoc is both a program and a Web server. It processes the source code of Go and extracts the document content in the package. Comments that appear before the top-level declaration and have no empty line between them will be extracted together with the declaration as the description document of the entry. The type and style of these comments determine the quality of the documents generated by godoc.

Each package should contain a package comment, that is, a block comment placed before the package clause. For packages that contain multiple files, package comments only need to appear in any one of them. Package comments should introduce the package as a whole and provide relevant information about the package. It will appear at the top of the godoc page and create detailed documentation for the content that follows.

/*
regexp Package implements a simple library for regular expressions.

The regular expression syntax accepted by the library is:

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
*/
package regexp

If a package is simple, the package comments can also be concise.

// The path package implements some common tools,
// To facilitate the operation of paths separated by backslashes

Comments do not require additional formatting, such as highlighting with an asterisk. The generated output may not even be displayed in a constant width font, so don't rely on space alignment. Godoc will handle all this like gofmt. Comments are plain text that will not be parsed, so things like HTML or something like this will be output as is, so they should not be used. The adjustment made by godoc is to display the indented text in equal width font to adapt to the corresponding program fragments. fmt package annotation uses this good effect.

Whether godoc reformats comments depends on the context, so you must make sure they look legible: use correct spelling, punctuation and sentence structure, collapse long lines, and so on.

In a package, the comments preceding any top-level declaration are used as document comments for that declaration. In the program, each exportable (capitalized) name should have a document comment.

It is better to have complete sentences for document annotation, so that it can adapt to various automatic displays. The first sentence should begin with what is declared and be a summary of a single sentence

// Compile is used to parse regular expressions and return, if yes
// Work, the Regexp object can be used to match the targeted text.
func Compile(str string) (*Regexp, error) {

If comments always start with the a name, output of the go doc command becomes more useful through grep. If you can't remember the name Compile and are looking for a regular expression parsing function ("parse" means the keyword is parse), you can run it

$ go doc -all regexp | grep -i parse

If all document comments in the package begin with This function... grep cannot help you remember this name. But since each package's document comment starts with its name, you can see this content, which shows the word you're looking for.

$ go doc -all regexp | grep -i parse
    Compile parses a regular expression and returns, if successful, a Regexp
    MustCompile is like Compile but panics if the expression cannot be parsed.
    parsed. It simplifies safe initialization of global variables holding
$

Go's declaration syntax allows group declarations. A single document comment should describe a set of related constants or variables. Because it is an overall statement, such notes are often more general.

// Error code returned after expression parsing failure
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)

Even for private names, the relationship between items can be indicated by group declarations, such as a group of variables protected by mutexes.

// Error code returned after expression parsing failure
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)

More free Golang knowledge, welcome to join Go Baodian | GOLANG ROADMAP
Invitation code: Gopher-1035-0722