You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by bm...@apache.org on 2022/10/16 20:59:46 UTC

[maven-plugin-tools] 01/01: [MPLUGIN-426] add @Description annotation

This is an automated email from the ASF dual-hosted git repository.

bmarwell pushed a commit to branch MPLUGIN-426_add_description_annotation
in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git

commit 9e6a87439e326f7a1c5e0db4ffb031defd5165a6
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Sun Oct 16 22:59:34 2022 +0200

    [MPLUGIN-426] add @Description annotation
---
 .../maven/plugins/annotations/Description.java     |  79 ++++++++++++++++
 .../JavaAnnotationsMojoDescriptorExtractor.java    |   9 +-
 .../datamodel/DescriptionAnnotationContent.java    | 102 +++++++++++++++++++++
 .../scanner/DefaultMojoAnnotationsScanner.java     |  22 +++++
 .../scanner/MojoAnnotationsScanner.java            |   3 +
 5 files changed, 212 insertions(+), 3 deletions(-)

diff --git a/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Description.java b/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Description.java
new file mode 100644
index 00000000..8dccc989
--- /dev/null
+++ b/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 &quot;Safe HTML&quot; 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();
+
+    /**
+     * The version of the plugin since when this goal or parameter was introduced (inclusive, optional).
+     *
+     * @return The version of the plugin since when this goal or parameter was introduced (inclusive) or an empty string
+     * of no since version has been given.
+     */
+    String since() default "";
+
+    /**
+     * Marks this Mojo goal or parameter as deprecated.
+     *
+     * @return {@code true} whether this Mojo goal or parameter is deprecated.
+     */
+    boolean deprecated() default false;
+
+    /**
+     * Deprecation reason (optional).
+     *
+     * @return an empty String if no deprecation reason has been given or a description.
+     */
+    String deprecatedBecause() default "";
+
+    /**
+     * Version since when this goal or parameter has been deprecated.
+     *
+     * @return the version since when this goal or parameter has been deprecated (inclusive) or an empty String if no
+     * version was given.
+     */
+    String deprecatedSince() default "";
+}
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
index 422d58c6..a3c46710 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
@@ -288,16 +288,19 @@ public class JavaAnnotationsMojoDescriptorExtractor
             MojoAnnotationContent mojoAnnotationContent = entry.getValue().getMojo();
             if ( mojoAnnotationContent != null )
             {
-                mojoAnnotationContent.setDescription( javaClass.getComment() );
+                if ( StringUtils.isEmpty( mojoAnnotationContent.getDescription() ) )
+                {
+                    mojoAnnotationContent.setDescription( javaClass.getComment() );
+                }
 
                 DocletTag since = findInClassHierarchy( javaClass, "since" );
-                if ( since != null )
+                if ( since != null && StringUtils.isEmpty( mojoAnnotationContent.getSince() ) )
                 {
                     mojoAnnotationContent.setSince( since.getValue() );
                 }
 
                 DocletTag deprecated = findInClassHierarchy( javaClass, "deprecated" );
-                if ( deprecated != null )
+                if ( deprecated != null && StringUtils.isEmpty( mojoAnnotationContent.getDeprecated() ) )
                 {
                     mojoAnnotationContent.setDeprecated( deprecated.getValue() );
                 }
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/DescriptionAnnotationContent.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/DescriptionAnnotationContent.java
new file mode 100644
index 00000000..e2380879
--- /dev/null
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/DescriptionAnnotationContent.java
@@ -0,0 +1,102 @@
+package org.apache.maven.tools.plugin.extractor.annotations.datamodel;
+
+/*
+ * 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.util.StringJoiner;
+
+/**
+ * @author Benjamin Marwell
+ * @since 3.7.0
+ */
+public class DescriptionAnnotationContent
+{
+
+    private String content;
+
+    private String since;
+
+    private boolean deprecated;
+
+    private String deprecatedBecause;
+
+    private String deprecatedSince;
+
+    public String getContent()
+    {
+        return content;
+    }
+
+    public void setContent( String content )
+    {
+        this.content = content;
+    }
+
+    public String getSince()
+    {
+        return since;
+    }
+
+    public void setSince( String since )
+    {
+        this.since = since;
+    }
+
+    public boolean isDeprecated()
+    {
+        return deprecated;
+    }
+
+    public void setDeprecated( boolean deprecated )
+    {
+        this.deprecated = deprecated;
+    }
+
+    public String getDeprecatedBecause()
+    {
+        return deprecatedBecause;
+    }
+
+    public void setDeprecatedBecause( String deprecatedBecause )
+    {
+        this.deprecatedBecause = deprecatedBecause;
+    }
+
+    public String getDeprecatedSince()
+    {
+        return deprecatedSince;
+    }
+
+    public void setDeprecatedSince( String deprecatedSince )
+    {
+        this.deprecatedSince = deprecatedSince;
+    }
+
+    @Override
+    public String toString()
+    {
+        return new StringJoiner( ", ", DescriptionAnnotationContent.class.getSimpleName() + "[", "]" )
+                .add( "content='" + content + "'" )
+                .add( "since='" + since + "'" )
+                .add( "deprecated=" + deprecated )
+                .add( "deprecatedBecause='" + deprecatedBecause + "'" )
+                .add( "deprecatedSince='" + deprecatedSince + "'" )
+                .toString();
+    }
+}
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/DefaultMojoAnnotationsScanner.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/DefaultMojoAnnotationsScanner.java
index 0407b8ea..16a05f4f 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/DefaultMojoAnnotationsScanner.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/DefaultMojoAnnotationsScanner.java
@@ -24,11 +24,13 @@ import javax.inject.Singleton;
 
 import org.apache.maven.artifact.Artifact;
 import org.apache.maven.plugins.annotations.Component;
+import org.apache.maven.plugins.annotations.Description;
 import org.apache.maven.plugins.annotations.Execute;
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 import org.apache.maven.tools.plugin.extractor.ExtractionException;
 import org.apache.maven.tools.plugin.extractor.annotations.datamodel.ComponentAnnotationContent;
+import org.apache.maven.tools.plugin.extractor.annotations.datamodel.DescriptionAnnotationContent;
 import org.apache.maven.tools.plugin.extractor.annotations.datamodel.ExecuteAnnotationContent;
 import org.apache.maven.tools.plugin.extractor.annotations.datamodel.MojoAnnotationContent;
 import org.apache.maven.tools.plugin.extractor.annotations.datamodel.ParameterAnnotationContent;
@@ -285,6 +287,16 @@ public class DefaultMojoAnnotationsScanner
                 mojoAnnotatedClass.setMojo( mojoAnnotationContent );
             }
 
+            // @Description annotation
+            mojoAnnotationVisitor = mojoClassVisitor.getAnnotationVisitor( Description.class );
+            if ( mojoAnnotationVisitor != null )
+            {
+                DescriptionAnnotationContent descriptionAnnotationContent = new DescriptionAnnotationContent();
+                populateAnnotationContent( descriptionAnnotationContent, mojoAnnotationVisitor );
+
+                mojoAnnotatedClass.getMojo().setDescription( descriptionAnnotationContent.getContent() );
+            }
+
             // @Execute annotation
             mojoAnnotationVisitor = mojoClassVisitor.getAnnotationVisitor( Execute.class );
             if ( mojoAnnotationVisitor != null )
@@ -306,11 +318,21 @@ public class DefaultMojoAnnotationsScanner
 
                 populateAnnotationContent( parameterAnnotationContent, fieldAnnotationVisitor );
 
+                DescriptionAnnotationContent descriptionAnnotationContent = new DescriptionAnnotationContent();
+                final MojoAnnotationVisitor descriptionAnnotationVisitor =
+                        annotationVisitorMap.get( Description.class.getName() );
+                if ( descriptionAnnotationVisitor != null )
+                {
+                    populateAnnotationContent( descriptionAnnotationContent, descriptionAnnotationVisitor );
+                }
+
                 if ( annotationVisitorMap.containsKey( Deprecated.class.getName() ) )
                 {
                     parameterAnnotationContent.setDeprecated( EMPTY );
                 }
 
+                parameterAnnotationContent.setDescription( descriptionAnnotationContent.getContent() );
+
                 mojoAnnotatedClass.getParameters().put( parameterAnnotationContent.getFieldName(),
                                                         parameterAnnotationContent );
             }
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/MojoAnnotationsScanner.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/MojoAnnotationsScanner.java
index a4e76199..43a27d20 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/MojoAnnotationsScanner.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/scanner/MojoAnnotationsScanner.java
@@ -20,6 +20,7 @@ package org.apache.maven.tools.plugin.extractor.annotations.scanner;
  */
 
 import org.apache.maven.plugins.annotations.Component;
+import org.apache.maven.plugins.annotations.Description;
 import org.apache.maven.plugins.annotations.Execute;
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
@@ -38,10 +39,12 @@ public interface MojoAnnotationsScanner
     String ROLE = MojoAnnotationsScanner.class.getName();
 
     List<String> CLASS_LEVEL_ANNOTATIONS = Arrays.asList( Mojo.class.getName(),
+                                                          Description.class.getName(),
                                                           Execute.class.getName(),
                                                           Deprecated.class.getName() );
 
     List<String> FIELD_LEVEL_ANNOTATIONS = Arrays.asList( Parameter.class.getName(),
+                                                          Description.class.getName(),
                                                           Component.class.getName(),
                                                           Deprecated.class.getName() );