doc-extract is a tool for extracting specially tagged comments in Go
source code. Tagged comments start with a blank line containing
+extract. Both grouped line comments (//) and block comments (/* */) are supported.
Go 1.16 and later:
go install github.com/joeshaw/doc-extract@latest
Go 1.15 and earlier:
go get -u github.com/joeshaw/doc-extract
Simply tag comments in your Go source code with +extract as the first
line of your comment. For example,
package main
// +extract
// API Documentation
// =================
//
// (TODO: add documentation)Then run the doc-extract command, providing it with a directory of
Go source files and an output file:
doc-extract ./example example.txt
Source files are processed in lexicographic order, except that a file
named doc.go gets highest priority. Comments within a file are
processed in the order they appear.
This predictable ordering allows you to add, for instance, a header to
the output file by adding it to doc.go.
The example directory contains an example using API
Blueprint.
This tool is especially useful for extracting documentation from comments when GoDoc isn't appropriate. For example, documentation for HTTP APIs. This could be used to extract API Blueprint for processing by Snowboard. Or it could be used to pull ReStructured Text (RST) for processing by Sphinx and the httpdomain extension.
This replaces my now-deprecated rst-extract tool.
Issues and pull requests are welcome. When filing a PR, please make
sure the code has been run through gofmt and that the tests pass.
MIT