go

Show comments in GoDoc

yyagi

y-yagi

Posted on October 21, 2018

Show comments in GoDoc

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.

💖 💪 🙅 🚩
yyagi
y-yagi

Posted on October 21, 2018

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Where GitOps Meets ClickOps
devops Where GitOps Meets ClickOps

November 29, 2024

How to Use KitOps with MLflow
beginners How to Use KitOps with MLflow

November 29, 2024