Skip to content

[MPLUGIN-421] Replace QDox with JavaParser for Javadoc extraction - #1150

Open
wilx wants to merge 4 commits into
apache:masterfrom
wilx:718-replace-qdox
Open

[MPLUGIN-421] Replace QDox with JavaParser for Javadoc extraction#1150
wilx wants to merge 4 commits into
apache:masterfrom
wilx:718-replace-qdox

Conversation

@wilx

@wilx wilx commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Summary

Replace the annotation extractor's QDox-backed Java source model with JavaParser and its symbol solver. This fixes descriptor generation for comment-only Java source files while retaining Javadoc extraction, reference resolution, and link generation.

Fixes #718.

Implementation

  • Add a JavaParser source model that resolves project sources, reactor output directories, dependency JARs, and the complete Java class library.
  • Port Mojo and parameter Javadoc extraction, member lookup, static-field values, module lookup, and internal/external link resolution from QDox to JavaParser.
  • Keep directory and JAR classpath entries visible through one class loader with platform-module delegation.
  • Add regression coverage for comment-only sources, mixed reactor/JAR inheritance, JDK platform modules, generated sources, and observable source-root exclusion.
  • Remove the annotation extractor's direct QDox dependency and update the dependency diagram.

The user-visible result is that valid projects containing a .java file with only comments no longer fail during the descriptor goal. Existing Javadoc metadata and links continue to be generated through the new model.

Validation

  • JAVA_HOME=/opt/jdks/latest-17 mvn spotless:apply
  • JAVA_HOME=/opt/jdks/latest-17 mvn -Prun-its verify
    • Maven Plugin Plugin ITs: 31 passed, 1 Maven-version-specific test skipped
    • Maven Plugin Report Plugin ITs: 12 passed

Following this checklist to help us incorporate your
contribution quickly and easily:

  • Your pull request should address just one issue, without pulling in other changes.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Each commit in the pull request should have a meaningful subject line and body.
    Note that commits might be squashed by a maintainer on merge.
  • Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied.
    This may not always be possible but is a best-practice.
  • Run mvn verify to make sure basic checks pass.
    A more thorough check will be performed on your pull request automatically.
  • You have run the integration tests successfully (mvn -Prun-its verify).

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

@wilx
wilx marked this pull request as ready for review August 7, 2026 22:40
@slachiewicz slachiewicz added dependencies Pull requests that update a dependency file enhancement New feature or request labels Aug 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[MPLUGIN-421] descriptor goal fails when there is .java file present with content that's just a comment

2 participants