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 "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();
+
+ /**
+ * 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() );