Go Doc

Go help developers generate documents by using godoc

Reference: https://golang.org/doc/effective_go

---

Generating godoc is fairly easy. The developer just put the comment on top of the file before the package clause, then the doc will be generated automatically.

There are two types of comment - block comment, and line comment

1.Block comment /* */ use for several lines of comment

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

The syntax of the regular expressions accepted is:

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

2.Line comment // use for a simple comment

// Package path implements utility routines for
// manipulating slash-separated filename paths.

For multi-file packages, the package comment only needs to be present in one file.

What should be in the comment?

1. Package introduction
2. Package explanation as a whole

Other than that you could comment on top of functions, interfaces or type, etc. to add further explanation

How to see godoc locally

A. cd into the package then run

go doc

This will show the doc in the terminal

---

B. If you want to see it on the local web

1.Make sure you have the go.mod file in the root directory
if you don't have it yet run

go mod init example/path

2.run

godoc

then it will run on localhost:6060

if you want to, you can specify your own port

godoc -http=localhost:8080