DEV Community 👩‍💻👨‍💻

y-yagi
y-yagi

Posted on

Show comments in GoDoc

#go

GoDoc show comments in code when runs godoc command with notes option. The notes option can specify regular expression matching note markers to show(default is BUG).

$ godoc --help
usage: godoc package [name ...] 
(snip)
  -notes string
        regular expression matching note markers to show (default "BUG") 
package exter

type Exter struct {
}

func NewExter() {
    // TODO(who): implement
    return Exter{}
}

func (exter *Exter) Run() error {
    // BUG(who): Not return correct value
    return nil
}

For example, there is a code the above, doc shows as follows.

doc

But if you remove (who) from comment, comment not shows in GoDoc.

This is because of the limit of GoDoc.

The notes need to write a comment as MARKER(uid): note body. Also, MAKER needs 2 or more uppercase [A-Z] letters and a UID of at least one character.

This is describing at Note type comment.
https://godoc.org/go/doc#Note

Regex for MARKER is here: https://github.com/golang/go/blob/035f9e8102d3b46877b7462fcd365324272d1d0e/src/go/doc/reader.go#L435

It is a little unusual for (uid) to be mandatory (at least for me ;) ), so be careful.

Top comments (1)

Collapse
moisoto profile image
Moises Soto

Nice post. The problem now is that godoc is no longer a command line utility.
Is nice to be able to display TODOs and BUGs on the doc server but if you know a way to show this using go doc subcommand please let me know.

🤔 Did you know?

 
✍️ Writing your own article is easy (we even support markdown).