javaxmlmavenmaven-pluginxml-documentation

Maven plugin plugin descriptor goal does not generate mojo description documentation when using annotations


According to the Maven Plugin Plugin documentation, when creating a Mojo, you are supposed to use an @Mojo(...) annotation to denote that your class is a Mojo. Then, when you run the plugin:descriptor goal, you should have various XML files created with details about your Mojo such as this one.

However, no matter what I do, I can't seem to get the XML files to be generated unless I use the deprecated @goal tag in my JavaDoc comment above the Mojo.

Here is a snippet of my pom.xml:

<project>
    ...
    <dependencies>
        <dependency>
            <!-- annotations used to describe the plugin metadata -->
            <groupId>org.apache.maven.plugin-tools</groupId>
            <artifactId>maven-plugin-annotations</artifactId>
            <version>3.9.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    ...
    <plugins>
       <plugin>
           <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-plugin-plugin</artifactId>
            <version>3.9.0</version>
            <executions>
                <execution>
                    <id>default-descriptor</id>
                    <phase>process-classes</phase>
                </execution>
                <execution>
                    <id>generate-helpmojo</id>
                   <goals>
                        <goal>helpmojo</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</project>

(You can find the full version here)

And here is an example of one of the Mojo's:

/**
 * Run the configured recipes and apply the changes locally.
 * <p>
 * This variant of rewrite:run will fork the maven life cycle and can be run as a "stand-alone" goal. It will
 * execute the maven build up to the process-test-classes phase.
 */
@Mojo(name = "run", requiresDependencyResolution = ResolutionScope.TEST, threadSafe = true,
        defaultPhase = LifecyclePhase.PROCESS_TEST_CLASSES)
@Execute(phase = LifecyclePhase.PROCESS_TEST_CLASSES)
public class RewriteRunMojo extends AbstractRewriteRunMojo {
}

(You can find the code for the full project here)

When I run the plugin:descriptor goal, I get an error that says: No mojo definitions were found for plugin: org.openrewrite.maven:rewrite-maven-plugin.

If I update my Mojo to have the @goal annotation in the JavaDoc such as in:

/**
 * Run the configured recipes and apply the changes locally.
 * <p>
 * This variant of rewrite:run will fork the maven life cycle and can be run as a "stand-alone" goal. It will
 * execute the maven build up to the process-test-classes phase.
 *
 * @goal run
 */
@Mojo(name = "run", requiresDependencyResolution = ResolutionScope.TEST, threadSafe = true,
        defaultPhase = LifecyclePhase.PROCESS_TEST_CLASSES)
@Execute(phase = LifecyclePhase.PROCESS_TEST_CLASSES)
public class RewriteRunMojo extends AbstractRewriteRunMojo {
}

then I correctly get a plugin-help.xml file that looks like:

<?xml version="1.0" encoding="UTF-8"?>

<!-- Generated by maven-plugin-tools 3.9 (for help'mojo with additional elements)-->

<plugin>
  <name>rewrite-maven-plugin</name>
  <description>Eliminate technical debt. At build time.</description>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>5.4.0-SNAPSHOT</version>
  <goalPrefix>rewrite</goalPrefix>
  <mojos>
    <mojo>
      <goal>run</goal>
      <description>Run the configured recipes and apply the changes locally. 
This variant of rewrite:run will fork the maven life cycle and can be run as a &quot;stand-alone&quot; goal. It will execute the maven build up to the process-test-classes phase.
</description>
      ....
    </mojo>
  </mojos>
</plugin>

Unfortunately, when I do this, I get a warning that I'm using a deprecated extractor. However, I can't figure out how to generate an XML file with information about the goals without using this deprecated path.

Does anyone have any idea what I might be doing wrong? Would greatly appreciate any advice.


Solution

  • java-annotations extractor discover annotation from compiled classes.

    So first you need compile your project.

    You need not execute direct goal plugin:descriptor it is bind in proper maven build phase.

    simply try:

    mvn process-classes
    

    You also not need:

    <execution>
     <id>default-descriptor</id>
     <phase>process-classes</phase>
    </execution>
    

    it is add by default for maven-plugin package