godocx

README

godocx

godocx is a command line tool to extract Go Doc Comments and transform to JSON. You can currate Go Doc Comments from various perspectives with output from godocx.

go doc command provides a way to transform Go Doc Comments to plain text, but it is not easy to currate the output. godoc command build a web server and provides a web interface to view Go Doc Comments, but it is not easy to filter or search. go/doc package provides a way to extract Go Doc Comments, but it is not easy to write codes for each perspectives.

Features

• Extract Go Doc Comments from multiple packages
• Annotate Go Doc Comments with a prefix @

Installation

$ go install github.com/dondakeshimo/godocx/cmd/godocx@latest

Usage

$ godocx -h
Godocx extracts Go Doc Comment and makes a JSON file.

Usage:

	gofmt [flags] [dirPath ...]

The flags are:

	-o file
		Write result to the file given path instead of stdout.
	-h -help
		Show help.

Godocx supports multiple dirPath which is both absolute and relative path.
Although, it does not support a wild card, or a three dots syntax like gofmt.
Please input each dirPaths separated by a space.

Documentation

Overview

Package godocx is the library for extracting Go documentation.

Index

• type DocEnvelope
  • func New(dirPaths []string) (*DocEnvelope, error)
• type Func
• type Note
• type Package
• type Type
• type Value

Types

type DocEnvelope

type DocEnvelope struct {
	Timestamp time.Time           `json:"timestamp"`
	Packages  map[string]*Package `json:"packages"`
}

DocEnvelope puts packages together. Last output of godocx should be this type.

func New

func New(dirPaths []string) (*DocEnvelope, error)

New creates a new DocEnvelope from the given directory paths.

type Func

type Func struct {
	Name        string   `json:"name"`
	Doc         string   `json:"doc"`
	Recv        string   `json:"recv"`
	Orig        string   `json:"orig"`
	Level       int      `json:"level"`
	Annotations []string `json:"annotations"`
}

Func is the documentation for a func declaration.

type Note

type Note struct {
	UID  string `json:"uid"`
	Body string `json:"body"`
}

A Note represents a marked comment starting with "MARKER(uid): note body". Any note with a marker of 2 or more upper case [A-Z] letters and a uid of at least one character is recognized. The ":" following the uid is optional.

type Package

type Package struct {
	Name       string             `json:"name"`
	ImportPath string             `json:"importPath"`
	Notes      map[string][]*Note `json:"notes"`
	Consts     []*Value           `json:"consts"`
	Vars       []*Value           `json:"vars"`
	Funcs      []*Func            `json:"funcs"`
	Types      []*Type            `json:"types"`
}

Package is the documentation for an entire package.

type Type

type Type struct {
	Name        string   `json:"name"`
	Doc         string   `json:"doc"`
	Annotations []string `json:"annotations"`
	Consts      []*Value `json:"consts"`
	Vars        []*Value `json:"vars"`
	Funcs       []*Func  `json:"funcs"`
}

Type is the documentation for a type declaration.

type Value

type Value struct {
	Name        string   `json:"name"`
	Doc         string   `json:"doc"`
	Annotations []string `json:"annotations"`
}

Value is the documentation for a var or const declaration.