[
https://issues.apache.org/jira/browse/MPLUGIN-426?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17618870#comment-17618870
]
Konrad Windszus commented on MPLUGIN-426:
-----------------------------------------
I don't get which issue we are trying to solve here. For Java we already
leverage the javadoc and the description may now even contain Javadoc links
(see MPLUGIN-417). For Kotlin just allow to reuse some of the logic from the
Java Annotations module.
I don't think there is ever a better description than provided via Javadoc!
> 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)
