docreflect/generate/lib.go

// Package generate produces Go source code that registers documentation for use with the docreflect package.
package generate

import "io"

// Options contains options for the generator.
type Options struct {

	// Main indicates that the docs for the symbols will be lookded up as part of the main package of an
	// executable. This is necessary, because the fully qualified Go path of symbols in a main package differs
	// from the path pointing to that package in a module.
	Main bool
}

// GenerateRegistry generates a Go source file containing an init function that registers the documentation for
// the declarations specified by their fully qualified Go path.
//
// The paths argument accepts arbitrary packages, package-level symbols, or struct fields. Usage of package
// paths is recommended over specific symbols in most cases.
//
// Limitations:
//
// - Type references (such as type aliases or definitions based on named types) are not resolved.
//
// - Import paths are not followed.
func GenerateRegistry(o Options, w io.Writer, outputPackageName string, path ...string) error {
	oo := initOptions()
	oo.isMain = o.Main
	d, err := generate(oo, path...)
	if err != nil {
		return err
	}

	if err := format(w, outputPackageName, d); err != nil {
		return err
	}

	return nil
}