joeshaw / doc-extract

Go tool for extracting text from specially tagged Go comments

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

doc-extract

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.

Installation

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

Usage

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.

Example

The example directory contains an example using API Blueprint.

Motivation

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.

Contributing

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.

License

MIT

About

Go tool for extracting text from specially tagged Go comments

License:MIT License


Languages

Language:HTML 77.9%Language:Go 20.5%Language:API Blueprint 1.5%