Replace or drop using of qdox

[slawekjaranowski]

New feature, improvement proposal

As qdox is deprecated and not more maintaned

• Next release paul-hammant/qdox#287

We should find alternative for it, or implement needed code in plugin.

[ascopes]

I was thinking about this recently and wondered if one option to consider could be replacing the logic that scrapes Mojo classes with an annotation processor that hooks into the Java Compiler.

It appears that the ProcessingEnvironment class within the annotation processing API can provide details on JavaDoc comments decorating annotations - see javadocs and the Mojo classes themselves are already driven by annotations that could be hooked into.

The help Mojo (in theory) could then be generated by collecting some JSON or XML blobs the AP emits that holds the details of each parameter in each Mojo.

Since the Javac implementation also supports the new markdown-style comments (/// foo), this could open the ability to support that.

This may also enable being able to generate docs for complex objects that have JavaDoc comments internally as well (at least, if they are in the same project), since that could be interrogated during compilation.

[ascopes]

I spent some time the other day looking into this and it does seem to be possible. I'm not sure on the exact semantics for how this needs to work though but I did draft the core skeleton of this locally. @slawekjaranowski would this be something of interest for me to contribute, in your opinion? I'd be happy to allocate some time when I am not working to try and contribute this but want to be sure it would be of interest before blindly committing any time to it.

The flow would look something like:

1. annotation processor uses javac APIs to process @Mojo annotations (+ @Parameter, @Inject, @Component, @Execute, etc).
2. annotation processor scrapes javadoc comments (and MD comments if on JDK23 or newer) for annotated elements. This uses the accessible sun APIs from the JDK. (Question of how this would work for Eclipse as I've had other issues with ECJ in the past unfortunately, but not sure that should be a total blocker for this).
3. annotation processor dumps JSON or XML files to target/classes or similar for each Mojo that it processes.
4. new generator in existing codebase scans for generated JSON/XML descriptors of each Mojo to present them back to the plugin descriptor.

Pros of this that I can see:

• Tightly bound to existing javac APIs, so no requirement on third party libs like QDox.
• Ability to mostly transparently cope with new javac features in the future (like MD javadoc comments - e.g. /// @since 1.2.3), since it relies on the public part of the compiler APIs rather than a third party library mimicking the parser structure. This would avoid issues such as Unable to parse generated classes during descriptor generation #944 more proactively).

Cons I can see:

• Annotation processing changes:
  • Need to explicitly specify the annotation processor on newer JDKs, so Maven Plugin configuration is a little more complex.
  • Cannot generate Help Mojos until after a compilation pass has completed.
  • These issues could be addressed by having a Maven plugin goal that calls the Javac compiler API to deal with annotation-processing-only passes prior to the main compilation phase?
• Multi step build is needed.

[cstamas]

Why not just drop it? qdox was used here to scrape javadoc tags, that predated Java 1.5 annotations, no?
I'd say just drop javadoc tag support, as since Java 1.5 (2004) annotations should be the default way to code Mojos, and not javadoc tags.

[cstamas]

wow, even if qdox is dropped, is pulled in by https://github.com/codehaus-plexus/plexus-languages (java)

[cstamas]

Or, consider something like https://github.com/forge/roaster
Is already used in maven-resolver and maven4 for document generation.

[ascopes]

@cstamas it seems the new java annotation path still relies on this to work as well unfortunately, which is why I've been blocked by GH-944 since last summer 😔.

From what I can tell, it is also scraping the generic comments for each parameter.