You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by GitBox <gi...@apache.org> on 2017/10/26 07:41:46 UTC
[GitHub] asfgit closed pull request #6: For Groovy/Scala Mojos: Allow Mojo documentation in annotations, too.
asfgit closed pull request #6: For Groovy/Scala Mojos: Allow Mojo documentation in annotations, too.
URL: https://github.com/apache/maven-plugin-tools/pull/6
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Mojo.java b/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Mojo.java
index e442310f..5a5d8d8c 100644
--- a/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Mojo.java
+++ b/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Mojo.java
@@ -117,4 +117,44 @@
* @return is thread safe
*/
boolean threadSafe() default false;
+
+ /**
+ * Description for this Mojo. Has the same format as a Javadoc comment body (that is, HTML with Javadoc inline
+ * tags).
+ *
+ * <p>Ordinarily, this information is taken from Javadoc comments. This annotation is used when documenting a Maven
+ * plugin that is written in a language other than Java, but which supports Java annotations, such as Groovy or
+ * Scala.</p>
+ *
+ * @since 3.5
+ */
+ String description() default "";
+
+ /**
+ * The first version of the plugin when this Mojo was added.
+ *
+ * <p>Ordinarily, this information is taken from Javadoc comments. This annotation is used when documenting a Maven
+ * plugin that is written in a language other than Java, but which supports Java annotations, such as Groovy or
+ * Scala.</p>
+ *
+ * @since 3.5
+ */
+ String since() default "";
+
+ /**
+ * The reason why this Mojo is deprecated.
+ *
+ * <p>If this is given, then the Mojo should also be annotated with {@code @}{@link Deprecated}, like so:</p>
+ *
+ * <pre><code>@Deprecated
+@Mojo(..., deprecated = "this Mojo is no longer used")
+public class ExampleMojo extends AbstractMojo { ... }</code></pre>
+ *
+ * <p>Ordinarily, this information is taken from Javadoc comments. This annotation is used when documenting a Maven
+ * plugin that is written in a language other than Java, but which supports Java annotations, such as Groovy or
+ * Scala.</p>
+ *
+ * @since 3.5
+ */
+ String deprecated() default "";
}
diff --git a/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Parameter.java b/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Parameter.java
index ec9dbcf6..f364e945 100644
--- a/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Parameter.java
+++ b/maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Parameter.java
@@ -85,4 +85,44 @@
* @return <code>true</code> if the user should not be allowed to configure the parameter directly
*/
boolean readonly() default false;
+
+ /**
+ * Description for this parameter. Has the same format as a Javadoc comment body (that is, HTML with Javadoc inline
+ * tags).
+ *
+ * <p>Ordinarily, this information is taken from Javadoc comments. This annotation is used when documenting a Maven
+ * plugin that is written in a language other than Java, but which supports Java annotations, such as Groovy or
+ * Scala.</p>
+ *
+ * @since 3.5
+ */
+ String description() default "";
+
+ /**
+ * The first version of the plugin when this parameter was added.
+ *
+ * <p>Ordinarily, this information is taken from Javadoc comments. This annotation is used when documenting a Maven
+ * plugin that is written in a language other than Java, but which supports Java annotations, such as Groovy or
+ * Scala.</p>
+ *
+ * @since 3.5
+ */
+ String since() default "";
+
+ /**
+ * The reason why this parameter is deprecated.
+ *
+ * <p>If this is given, then the parameter should also be annotated with {@code @}{@link Deprecated}, like so:</p>
+ *
+ * <pre><code>@Deprecated
+@Parameter(..., deprecated = "this parameter is no longer used")
+private String oldParameterThatNowDoesNothing;</code></pre>
+ *
+ * <p>Ordinarily, this information is taken from Javadoc comments. This annotation is used when documenting a Maven
+ * plugin that is written in a language other than Java, but which supports Java annotations, such as Groovy or
+ * Scala.</p>
+ *
+ * @since 3.5
+ */
+ String deprecated() default "";
}
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/MojoAnnotationContent.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/MojoAnnotationContent.java
index 33104cb8..663435ff 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/MojoAnnotationContent.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/MojoAnnotationContent.java
@@ -207,6 +207,36 @@ public void name( String name )
this.name = name;
}
+ public String deprecated()
+ {
+ return getDeprecated();
+ }
+
+ public void deprecated( String deprecated )
+ {
+ setDeprecated( deprecated );
+ }
+
+ public String description()
+ {
+ return getDescription();
+ }
+
+ public void description( String description )
+ {
+ setDescription( description );
+ }
+
+ public String since()
+ {
+ return getSince();
+ }
+
+ public void since( String since )
+ {
+ setSince( since );
+ }
+
@Override
public String toString()
{
@@ -226,6 +256,9 @@ public String toString()
sb.append( ", inheritByDefault=" ).append( inheritByDefault );
sb.append( ", configurator='" ).append( configurator ).append( '\'' );
sb.append( ", threadSafe=" ).append( threadSafe );
+ sb.append( ", deprecated='" ).append( deprecated() ).append( '\'' );
+ sb.append( ", description='" ).append( description() ).append( '\'' );
+ sb.append( ", since='" ).append( since() ).append( '\'' );
sb.append( '}' );
return sb.toString();
}
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/ParameterAnnotationContent.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/ParameterAnnotationContent.java
index 919aaa4b..ca8a49fc 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/ParameterAnnotationContent.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/datamodel/ParameterAnnotationContent.java
@@ -63,6 +63,16 @@ public ParameterAnnotationContent( String fieldName, String alias, String proper
this.readonly = readonly;
}
+ public ParameterAnnotationContent( String fieldName, String alias, String property, String defaultValue,
+ boolean required, boolean readonly, String className,
+ String deprecated, String description, String since )
+ {
+ this( fieldName, alias, property, defaultValue, required, readonly, className );
+ deprecated( deprecated );
+ description( description );
+ since( since );
+ }
+
public String name()
{
return name;
@@ -123,6 +133,36 @@ public void readonly( boolean readonly )
this.readonly = readonly;
}
+ public String deprecated()
+ {
+ return getDeprecated();
+ }
+
+ public void deprecated( String deprecated )
+ {
+ setDeprecated( deprecated );
+ }
+
+ public String description()
+ {
+ return getDescription();
+ }
+
+ public void description( String description )
+ {
+ setDescription( description );
+ }
+
+ public String since()
+ {
+ return getSince();
+ }
+
+ public void since( String since )
+ {
+ setSince( since );
+ }
+
public Class<? extends Annotation> annotationType()
{
return null;
@@ -150,6 +190,9 @@ public String toString()
sb.append( ", defaultValue='" ).append( defaultValue ).append( '\'' );
sb.append( ", required=" ).append( required );
sb.append( ", readonly=" ).append( readonly );
+ sb.append( ", deprecated='" ).append( deprecated() ).append( '\'' );
+ sb.append( ", description='" ).append( description() ).append( '\'' );
+ sb.append( ", since='" ).append( since() ).append( '\'' );
sb.append( '}' );
return sb.toString();
}
@@ -194,6 +237,18 @@ public boolean equals( Object o )
{
return false;
}
+ if ( deprecated() != null ? !deprecated().equals( that.deprecated() ) : that.deprecated() != null )
+ {
+ return false;
+ }
+ if ( description() != null ? !description().equals( that.description() ) : that.description() != null )
+ {
+ return false;
+ }
+ if ( since() != null ? !since().equals( that.since() ) : that.since() != null )
+ {
+ return false;
+ }
return true;
}
@@ -207,6 +262,9 @@ public int hashCode()
result = 31 * result + ( defaultValue != null ? defaultValue.hashCode() : 0 );
result = 31 * result + ( required ? 1 : 0 );
result = 31 * result + ( readonly ? 1 : 0 );
+ result = 31 * result + ( deprecated() != null ? deprecated().hashCode() : 0 );
+ result = 31 * result + ( description() != null ? description().hashCode() : 0 );
+ result = 31 * result + ( since() != null ? since().hashCode() : 0 );
return result;
}
}
diff --git a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/FooMojo.java b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/FooMojo.java
index 673f8b1a..ee8527b2 100644
--- a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/FooMojo.java
+++ b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/FooMojo.java
@@ -33,7 +33,7 @@
/**
* @author Olivier Lamy
*/
-@Mojo( name = "foo", defaultPhase = LifecyclePhase.COMPILE, threadSafe = true )
+@Mojo( name = "foo", defaultPhase = LifecyclePhase.COMPILE, threadSafe = true, description = "This is a description.", since = "3.5", deprecated = "because I said so" )
@Execute( goal = "compiler", lifecycle = "my-lifecycle", phase = LifecyclePhase.PACKAGE )
public class FooMojo
extends AbstractMojo
@@ -52,6 +52,10 @@
@Parameter( property = "thebeer", defaultValue = "coolbeer" )
protected String beer;
+ @Parameter( description = "wine for french folks", since = "forever ago", deprecated = "beer is better" )
+ @Deprecated
+ protected String wine;
+
/**
* Plexus compiler manager.
*/
diff --git a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/TestAnnotationsReader.java b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/TestAnnotationsReader.java
index 17a24bfd..12359bee 100644
--- a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/TestAnnotationsReader.java
+++ b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/TestAnnotationsReader.java
@@ -71,6 +71,9 @@ public void testReadMojoClass()
assertEquals( true, mojo.threadSafe() );
assertEquals( false, mojo.aggregator() );
assertEquals( LifecyclePhase.COMPILE, mojo.defaultPhase() );
+ assertEquals( "This is a description.", mojo.description() );
+ assertEquals( "3.5", mojo.since() );
+ assertEquals( "because I said so", mojo.deprecated() );
Execute execute = mojoAnnotatedClass.getExecute();
@@ -82,9 +85,12 @@ public void testReadMojoClass()
Assertions.assertThat( components ).isNotNull().isNotEmpty().hasSize( 2 );
Collection<ParameterAnnotationContent> parameters = mojoAnnotatedClass.getParameters().values();
- Assertions.assertThat( parameters ).isNotNull().isNotEmpty().hasSize( 2 ).contains(
+ Assertions.assertThat( parameters ).isNotNull().isNotEmpty().hasSize( 3 ).contains(
new ParameterAnnotationContent( "bar", null, "thebar", "coolbar", true, false, String.class.getName() ),
new ParameterAnnotationContent( "beer", null, "thebeer", "coolbeer", false, false,
- String.class.getName() ) );
+ String.class.getName() ),
+ new ParameterAnnotationContent( "wine", null, null, null, false, false,
+ String.class.getName(), "beer is better", "wine for french folks",
+ "forever ago" ) );
}
}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org