[jira] [Updated] (MPLUGIN-426) Description annotation for Mojo and Parameters

["Herve Boutemy (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/MPLUGIN-426?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Herve Boutemy updated MPLUGIN-426:
----------------------------------
    Summary: Description annotation for Mojo and Parameters  (was: MojoDescription annotation)

> Description annotation for Mojo and Parameters
> ----------------------------------------------
>
>                 Key: MPLUGIN-426
>                 URL: https://issues.apache.org/jira/browse/MPLUGIN-426
>             Project: Maven Plugin Tools
>          Issue Type: New Feature
>          Components: maven-plugin-annotations, Plugin Plugin
>    Affects Versions: 3.4, 3.5.2, 3.6.4
>            Reporter: Benjamin Marwell
>            Priority: Major
>
> Hey all!
> h2. 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).
> h2. Downsides of custom extractors
>  # Setting up as a user is complicated, see this example:
> {code:java}
>             <!-- 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> {code}
>  # More dependencies to update!
>  # 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).
> h2. 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.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)