usagegen

README

Command usagegen reads "main" package godoc and creates source file that
defines constant holding extracted text.

It is intended to be used by command line tools that print package
documentation as part of their usage help, for example, when invoked with -h
flag.

When run in a directory holding main package source, it extracts its
documentation and creates automatically generated file (usage_generated.go
by default) that defines single constant named "usage".

This constant can then be used in code like this:

    func init() {
    	flag.Usage = func() {
    		fmt.Fprintln(flag.CommandLine.Output(), usage)
    		fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n",
    			filepath.Base(os.Args[0]))
    		flag.PrintDefaults()
    	}
    }

If program uses flag package, then when run with -h flag it will output
godoc text followed by list of supported flags as printed by
flag.PrintDefaults.

If usagegen is called with -autohelp flag, it generates source file that
defines single init() function that sets flag.Usage variable as in above
example, but usage constant instead only scoped to this init function.

It can be used with go generate by including this line somewhere in main
package source:

    //go:generate usagegen -autohelp

Then whenever package documentation is updated, run "go generate" to
regenerate source file with usage text.

Documentation

Overview

Command usagegen reads "main" package godoc and creates source file that defines constant holding extracted text.

It is intended to be used by command line tools that print package documentation as part of their usage help, for example, when invoked with -h flag.

When run in a directory holding main package source, it extracts its documentation and creates automatically generated file (usage_generated.go by default) that defines single constant named "usage".

This constant can then be used in code like this:

func init() {
	flag.Usage = func() {
		fmt.Fprintln(flag.CommandLine.Output(), usage)
		fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n",
			filepath.Base(os.Args[0]))
		flag.PrintDefaults()
	}
}

If program uses flag package, then when run with -h flag it will output godoc text followed by list of supported flags as printed by flag.PrintDefaults.

If usagegen is called with -autohelp flag, it generates source file that defines single init() function that sets flag.Usage variable as in above example, but usage constant instead only scoped to this init function.

It can be used with go generate by including this line somewhere in main package source:

//go:generate usagegen -autohelp

Then whenever package documentation is updated, run "go generate" to regenerate source file with usage text.