DEV Community

loading...

Go Doc

#go
nicha
・1 min read

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
Enter fullscreen mode Exit fullscreen mode

2.Line comment // use for a simple comment

// Package path implements utility routines for
// manipulating slash-separated filename paths.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

2.run

godoc
Enter fullscreen mode Exit fullscreen mode

then it will run on localhost:6060

if you want to, you can specify your own port

godoc -http=localhost:8080
Enter fullscreen mode Exit fullscreen mode

Discussion (0)

Forem Open with the Forem app