Skip to content

Extract Mojo metadata with a custom doclet instead of javaparser and ASM #1277

Open

Description

@slachiewicz

Follow-up to #1080, from this comment.

Mojo descriptors are built with two third-party libraries: ASM reads the annotations from bytecode (DefaultMojoAnnotationsScanner and its visitors), and javaparser-core with the symbol solver reads Javadoc from sources (JavaSourceModel, the converter package).

Proposal: a custom doclet on the JDK's jdk.javadoc.doclet API, run in process through ToolProvider.getSystemDocumentationTool(), as the configuration collector in apache/maven-resolver@46da42c does. The doclet would:

  • read @Mojo, @Parameter, @Component and @Execute as javax.lang.model elements, so ASM can go;
  • convert the description and the standard tags (@since, @deprecated, @see, inline {@link}, {@code}, {@value}) from DocTree nodes into the descriptor's description, since and deprecated fields;
  • pick up Markdown doc comments (///) when it runs on JDK 23 or later.

Open questions:

  • Mojos that extend classes from dependencies: the doclet has no source for them, so ASM or a -sources.jar lookup may have to stay for that path.
  • The doclet API needs JDK 9 or later; the 3.x line targets Java 8.
  • The annotation processor approach suggested in Replace or drop using of qdox #1080 is the alternative. The doclet runs from the plugin goal and does not change how users compile.

Done when the plugin descriptors and plugin-help.xml produced by the existing ITs are unchanged, and maven-plugin-tools-annotations no longer depends on javaparser or ASM.

Activity

  1. kwin commented on Nov 15, 2026

    @kwin
    Member

    Regarding the questions:

    1. Javadoc extraction without source: That does not work with neither QDox/javaparser-core, so no regression. Would be good to emit a warning in that case, though
    2. Doclet API: The legacy one from https://docs.oracle.com/javase/8/docs/jdk/api/javadoc/doclet/index.html is available in Java 8.
    3. Annotation processor, whether the plugin descriptor is called from an Annotation processor or from a Mojo should only have minor impact as in both cases the custom doclet would need to be called.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions