1.9 KiB
Docreflect
Library and tooling to help accessing go doc comments during runtime.
The docreflect library provides functions to access the Go doc based documentation of Go runtime objects, like types, functions and methods, struct fields, or packages, during runtime, using their reflection handle to look up the right snippet.
To be able to do that, the documentation needs to be captured during build time.
Generating GoDoc registry code:
Go doc comments are not accessible during runtime via reflection. To make them avaiable during runtime, we need to capture them during build time. The docreflect command, or the docreflect/generate library package, fetches the go doc comments of the specified declarations, and generates Go code that registers the docs for every declaration. Code that includes the generated initialization code, will have the docs accessible via the top level docreflect package methods.
Declarations:
- the declarations must be absolute Go paths
- when passing in the import path of a package, all the top level symbols of the package, plus the struct fields and methods of the top level types will be included
- the package documentation can be fetched using
docreflect.Docs("absolute/import/path/of/package") - when passing in the import path of only the selected symbols, the rest of the package level symbols will be ignroed
Gotchas:
- type aliases and type definitions based on named types are not resolved
- package imports are not resolved, necessary packages need to be included in the generate arguments
Library documentation: https://godocs.io/code.squareroundforest.org/arpio/docreflect
To install the docreflect command, run:
make install
Usage of the docreflect command:
docreflect \
mypackage \
coderepos.org/jdoe/mypackage \
coderepos.org/jdoe/otherpackage \
> docreflect.go
Made in Berlin, DE