Description annotation for Mojo and Parameters

Hey all!

Overview

This is actually reopening https://issues.apache.org/jira/browse/MPLUGIN-247 which was closed as won't fix.

I tried to implement a kotlin parser, but it is really hard to do so, because you cannot reuse any of the Methods from JavaAnnotationsParser.

That said, someone used messy reflections for this: https://github.com/random-maven/maven-plugin-tools-annotations/blob/35371c19004622645f87c35c2317a7c860b924a5/src/main/java/com/carrotgarden/maven/tools/Extractor.java#L57-L67

Trying this without reflection will lead you to iterate over files again and again (here's a barebone): https://github.com/bmarwell/maven-plugin-tools-kotlin-extractor/blob/main/src/main/java/org/apache/maven/tools/plugin/extractor/kotlin/KotlinKdocExtractor.java#L80-L87

Tamas' request was to have one extractor per JVM language in a separate project. But due to his current API changes, this would be a lot of work to do! https://github.com/apache/maven-plugin-tools/commit/ba8eb2dc52fb406f9e3897c9577f0bf0d4b0f0fc especially you'd have to mantain multiple versions (<3.7,  >= 3.7).

Downsides of custom extractors

1. Setting up as a user is complicated, see this example:

            <!-- Generate plugin.xml descriptor. -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-plugin-plugin</artifactId>
                <dependencies>
                   <!-- Provide custom extractor. -->
                    <dependency>
                        <groupId>com.carrotgarden.maven</groupId>
                        <artifactId>maven-plugin-tools-annotations</artifactId>
                        <version>[1,2)</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <goalPrefix>bintray</goalPrefix>
                    <extractors>
                        <!-- Use only custom extractor. -->
                        <extractor>java-annotations-extra</extractor>
                    </extractors>
                </configuration>
            </plugin> 

1. More dependencies to update!
2. You need two versions: One for plugin-tools <3.7 and one for plugin tools >=3.7 due to API incompatiblity (new interface methods without defaults).

Alternative: Provide @Description annotation

That said, just adding a description mojo with fields "description", "since", "deprecated" would be the easiest way to solve this. It is easily backwards compatible (just use javadoc if no annotation is present) and it is similar to what OpenAPI annotations do - they do not parse javadoc either. Besides, Javadoc can have a different level of detail comparing to the Mojo Descrption. So a separation might be feasible after all!

This enables plugins written in scala, kotlin and groovy (and any fancy language for the JVM in the future) to be written with full documentation, without requiring maven-plugin-plugin to have per-language extension and source code parser dependency.