Document and expose documentation of BuildItems in an automated fashion

[emmanuelbernard]

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?).

[machi1990]

2. build an anotation processor that will collect the BuildItems and generate a list of them per extension and a documentation (summary?).

Is publishing a JavaDoc another option that has been considered?

[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).

[emmanuelbernard]

1. build an anotation processor that will collect the BuildItems and generate a list of them per extension and a documentation (summary?).

Is publishing a JavaDoc another option that has been considered?

We can consider that but then filtered by BuildItem? Also how do you get a view of all of them (same problem config had and we ended up creating a all page).

[emmanuelbernard]

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?

[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.

[manovotn]

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

So you will keep the package the same, but place it in a different module and then your deployment module will depend on the spi module? Since that's the only way not to break existing extensions, right?

What I don't like about that is that you will have two equal packages coming from two different JARs which, if I recall correctly, is something Java 9+ doesn't like (I know we don't care about modules much, but we still shouldn't go against the practices, right?).
It will also spawn tons of extra maven modules as many extensions will now consist of three modules instead of two, making it (IMO) less understandable for extension writers.

[dmlloyd]

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

So you will keep the package the same, but place it in a different module and then your deployment module will depend on the spi module? Since that's the only way not to break existing extensions, right?

Well, firstly, I want to point out that this issue is not about compatibility or any kind of change. It's purely about documentation. So, if a build item is not in an SPI module, it's not considered public and not documented as such.

Secondly, no, because split packages are not allowed, period.

What I don't like about that is that you will have two equal packages coming from two different JARs which, if I recall correctly, is something Java 9+ doesn't like (I know we don't care about modules much, but we still shouldn't go against the practices, right?).
It will also spawn tons of extra maven modules as many extensions will now consist of three modules instead of two, making it (IMO) less understandable for extension writers.

Yes, this is true, but it's a reality of the design we've chosen. Not having public/shareable items be separate from the deployment module is just not a viable approach.

[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 :-)