gonote

README

gonote

Library and CLI tool for parsing Go project documentation notes

Overview

gonote provides the ability to recursively parse a Go project space for godoc notes. These notes are described in the godoc library documentation.

Godoc notes are structured comments found in Go source code. These notes take the form of a marker, an UID, and a body:

MARKER(uid): note body

The marker labels the category of comment. For example, you may have a comment related to describing a known bug, in which case the marker would be BUG. You could also have a marker for labeling a TODO item, where the marker would be TODO. In both cases, the UID could be a username responsible for following up on that issue. The note body contains any related details.

Examples

Here are a few examples of godoc notes from the Go standard library:

• TODO(mundaym): merge with case 24.
• TODO(rogpeppe): re-enable this test in https://go-review.googlesource.com/#/c/5910/
• TODO(rsc): Decide which tests are enabled by default.
• BUG(brainman): This package is not implemented on Windows. As the syslog package is frozen, Windows users are encouraged to use a package outside of the standard library. For background, see https://golang.org/issue/1108.
• BUG(akumar): This package is not implemented on Plan 9.
• BUG(rsc): FieldByName and related functions consider struct field names to be equal if the names are equal, even if they are unexported names originating in different packages.

Installation

gonote requires Go v1.10+ and a valid Go workspace.

To install:

go get -u github.com/pokstad/gonote/gonote

Usage

  OVERVIEW:

    gonote scans Go source code files for notations

  USAGE:

    gonote [OPTIONS] TARGET

  TARGET:

    the Go package path you wish to scan

  OPTIONS:

    -output [json|text|textmate]

Documentation

Index

• func AllNotes(target, base string) (map[string][]Note, error)
• type Note
  • func (n Note) String() string

Functions

func AllNotes

func AllNotes(target, base string) (map[string][]Note, error)

AllNotes returns all notes for all packages in a directory

Types

type Note

type Note struct {
	Tag  string
	UID  string
	Body string
	Loc  gomate.CodeRef
}

Note is a godoc note found in Go source code comments

func (Note) String

func (n Note) String() string