[
https://issues.apache.org/jira/browse/MPLUGIN-426?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17618697#comment-17618697
]
ASF GitHub Bot commented on MPLUGIN-426:
----------------------------------------
bmarwell commented on code in PR #152:
URL: https://github.com/apache/maven-plugin-tools/pull/152#discussion_r996695910
##########
maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Description.java:
##########
@@ -0,0 +1,79 @@
+package org.apache.maven.plugins.annotations;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Describes a {@code Mojo} or a Mojo’s {@code Parameter} when JavaDoc
extraction is not feasible (because of deviating
+ * documentation goals) or not possible (e.g. for other JVM languages like
Scala, Groovy or Kotlin).
+ */
+@Documented
+@Retention( RetentionPolicy.CLASS )
+@Target( { ElementType.TYPE, ElementType.FIELD } )
+@Inherited
+public @interface Description
+{
+ /**
+ * Description content for the {@code Mojo} or Mojo {@code Parameter}.
+ *
+ * <p>A "Safe HTML" subset can be used. This is achieved by
running
+ * the content through the <a
href="https://github.com/owasp/java-html-sanitizer";<OWASP Java HTML
Sanitizer</a>
+ * before rendering.</p>
+ *
+ * @return a description of the Mojo or the parameter.
+ */
+ String content();
Review Comment:
Yes, that was my first idea. But since it contains HTML, I thought it might
be a good idea to not use "value". But then, what would value be if added
later...
Can change that. Will also add tests.
> 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)
