docreflect/readme.md

# 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*