Document and expose documentation of BuildItems in an automated fashion

A big value of extensions is the BuildItem model. We need to document them so other extension writers can discover and use them. They are also part of the extension contract.

1. document all “public” BuildItem with adequate JavaDoc
2. build an anotation processor that will collect the BuildItems and generate a list of them per extension and a documentation (summary?).

[dmlloyd]

It would be nice if we could use structural means to validate that a build item is “public”: that is, it must be public (obviously) but must also reside in an spi module (not deployment).

Do you mean module or package?

Module. Build items not in separate spi modules historically cause dependency issues.

[Ladicek]

I have some experience with generating documentation from annotations using an annotation processor and a Maven plugin (see https://github.com/Ladicek/ann-docu-gen, which is a prototype I built in my free time and then used in an internal project).

I can see how I’d collect build steps and generate documentation for them, but build items are not annotated in any way and when present in an spi module, there doesn’t have to be any annotation at all. For example, I’m just looking at the quarkus-kubernetes-spi module (because I’m at least a little familiar with the Kubernetes extension), and it only has 4 classes = build items, no annotation whatsoever, so not sure how an annotation processor would catch any of them. It would be possible to look for build steps and collect build items from them, but then the annotation processor wouldn’t have access to the source of all the build items (e.g. to the ones in quarkus-kubernetes-spi) and would only generate a very limited documentation.

One idea that would be more generally applicable, but would also help here: if we used annotations to indicate API stability (@API-style), the annotation processor could look for them (and then check superclasses to figure out what is a build item).

EDIT: I guess what I wanted to say is: I’d volunteer to work on this, but I see an insurmountable issue before I could even get started 😃