META-INF/maven/plugin.xml descriptor|http://maven.apache.org/ref/current/maven-plugin-api/plugin.html], which is in general generated by [maven-plugin-plugin|http://maven.apache.org/plugins/maven-plugin-plugin/]. Information for the generator are written as javadoc annotations in java source

: see [maven-plugin-tools-java|http://maven.apache.org/plugin-tools/maven-plugin-tools-java

/index.html].

Using java 5 annotations instead of javadoc ones have multiple benefits:

* compile-time checks for plugin metadata, with enums for some annotations
* inheritance support
* annotations are supported in most IDEs, providing code-completion and syntactic checks

see [plexus-component-annotations|http://plexus.codehaus.org/plexus-containers/plexus-component-annotations/] for an example of such a work done on Plexus.

h1. Existing implementations

Multiple implementations of such annotations exist:
* JFrog's Maven Anno Mojo: see [the wiki|http://wiki.jfrog.org/confluence/display/OSS/Maven+Anno+Mojo] or [annotations source|https://github.com/JFrogDev/maven-anno-mojo/tree/master/maven-plugin-anno/src/main/java/org/jfrog/maven/annomojo/annotations],
the idea is having as much annotations as actual [javadoc annotations|http://maven.apache.org/plugin-tools/maven-plugin-tools-java/index.html], each with only 1 attribute
* Maven [MNG-2521|http://jira.codehaus.org/browse/MNG-2521], with [its proposal from 2007|https://cwiki.apache.org/confluence/display/MAVENOLD/Java+5+Annotations+for+Plugins] providing [a source branch|https://svn.apache.org/repos/asf/maven/components/branches/MNG-2521/] and [its annotations|https://svn.apache.org/repos/asf/maven/components/branches/MNG-2521/maven-plugin-tools/maven-plugin-tools-java5/src/main/java/org/apache/maven/tools/plugin/],
the idea is having only 4 annotations each with multiple attributes: Goal + Execute and Parameter + Component

h1. Proposal

Continue the work started on MNG-2521 before plugin-tools extraction from Maven Core.

Annotations:
* 4 annotations: @Mojo and @Execute at class-level, @Parameter and @Component at field level
* java package: org.apache.maven.tools.plugin.annotations (consistent with [maven-plugin-tools-api|http://maven.apache.org/plugin-tools/maven-plugin-tools-api

/apidocs/index.html]
* a new maven-plugin-tools-annotations component in [plugin-tools

|http://maven.apache.org/plugin-tools/]

Extractor: addition into existing [maven-plugin-tools-java|http://maven.apache.org/plugin-tools/maven-plugin-tools-java

/index.html]

h1. New features

* use annotations from parents classes coming from reactors and external dependencies.

h1. Implementation

Initial work done in trunk [http://svn.apache.org/repos/asf/maven/plugin-tools/trunk/

|http://svn.apache.org/repos/asf/maven/plugin-tools/branches/MPLUGIN-189/]

The maven-plugin-plugin version has been bump to 3.0-SNAPSHOT.

h2.

 State of the development as of 22/5/2012

Following usage for a plugin developer is working, with annotations near previous javadoc tags:

{code

:java

}
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugins.annotations.ResolutionScope;
import org.apache.maven.plugins.annotations.Component;
import org.apache.maven.plugins.annotations.Execute;
import org.apache.maven.plugins.annotations.InstanciationStrategy;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;

/**
 * Mojo Description. @Mojo( name = "<goalName>" ) is the minimal required annotation.
 * @since <since-text>
 * @deprecated <deprecated-text>
 */
@Mojo( name = "<goalName>",
       aggregator = <false|true>,
       configurator = "<roleHint>",
       executionStrategy = "<once-per-session|always>",
       inheritByDefault = <true|false>,
       instantiationStrategy = InstanciationStrategy.<strategy>,
       defaultPhase = "<phaseName>",
       requiresDependencyResolution = ResolutionScope.<scope>,
       requiresDependencyCollection = ResolutionScope.<scope>, // (since Maven 3.0)
       requiresDirectInvocation = <false|true>,
       requiresOnline = <false|true>,
       requiresProject = <true|false>,
       requiresReports = <false|true>, // (unsupported since Maven 3.0)
       threadSafe = <false|true> ) // (since Maven 3.0)
@Execute( goal = "<goalName>",
          phase = LifecyclePhase.<phase>
          lifecycle = "<lifecycleId>" )
public class MyMojo
    extends AbstractMojo
{
    /**
     * @since <since-text>
     * @deprecated <deprecated-text>
     */
    @Parameter( alias = "myAlias",
                property = "aProperty",
                defaultValue = "${anExpression}",
                readonly = <false|true>
                required = <false|true> )
    private String parameter;

    /**
     * @since <since-text>
     * @deprecated <deprecated-text>
     */
    @Component( role = "MyComponentExtension..."class,
                roleHint = "..." )
    private MyComponent component;

    public void execute()
    {
        ...
    }
}
{code}


h2. Improvement Idea HBO-1

rename roleHint to hint to match Plexus @Requirement


{code:java}
    @Component( role = MyComponentExtension.class,
                hint = "..." )
    private MyComponent component;
{code}


h2. Improvement Idea HBO-2

Remove readonly attribute from @Parameter (was used for Maven components like ${project} to mark that it should not be configured by plugin user), and replace by a new attribute of @Component which is mutually exclusive with role+hint


{code:java}
    @Component( expression = "project" )
    private MavenProject project;
{code}


h2. Improvement Idea HBO-3

Introduce JSR-330, by requiring plugin developer to mark injected fields with standard @Inject and make @Parameter and @Component standard Qualifier.
Costs more writing for plugin developer (these @Inject) without much win other than mark the intent in a standard way (and should change much for maven-plugin-tools)