[MPLUGIN-124] The generated documentation for a Mojo should show if it is a build plugin or a reporting plugin

o This renders text corresponding to @requiresReport. There is no metadata that I can find
that answers the question 'Can this be invoked as a reporting plugin'


git-svn-id: https://svn.apache.org/repos/asf/maven/plugin-tools/trunk@1164545 13f79535-47bb-0310-9956-ffa450edef68

maven-plugin-plugin/src/it/plugin-report/pom.xml

@@ -42,6 +42,16 @@ under the License.
       <artifactId>maven-plugin-api</artifactId>
       <version>2.0</version>
     </dependency>
+    <dependency>
+      <groupId>org.apache.maven.reporting</groupId>
+      <artifactId>maven-reporting-impl</artifactId>
+      <version>2.0.5</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven.reporting</groupId>
+      <artifactId>maven-reporting-api</artifactId>
+      <version>3.0</version>
+    </dependency>
   </dependencies>
 
   <build>

maven-plugin-plugin/src/it/plugin-report/src/main/java/org/DummyReport.java

@@ -0,0 +1,210 @@
+package org;
+
+/*
+ * 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.io.File;
+import java.util.Locale;
+import java.util.ResourceBundle;
+
+import org.apache.maven.doxia.sink.Sink;
+import org.apache.maven.doxia.siterenderer.Renderer;
+import org.apache.maven.project.MavenProject;
+import org.apache.maven.reporting.AbstractMavenReport;
+import org.apache.maven.reporting.AbstractMavenReportRenderer;
+import org.apache.maven.reporting.MavenReportException;
+
+/**
+ * Dummy Reporting Plugin.
+ *
+ * @goal report
+ * @requiresReports true
+ * @execute phase="compile"
+ */
+public class DummyReport
+    extends AbstractMavenReport
+{
+    /**
+     * Report output directory.
+     *
+     * @parameter default-value="${project.build.directory}/generated-site/xdoc"
+     */
+    private File outputDirectory;
+
+    /**
+     * Doxia Site Renderer.
+     *
+     * @component
+     */
+    private Renderer siteRenderer;
+
+    /**
+     * The Maven Project.
+     *
+     * @parameter expression="${project}"
+     * @required
+     * @readonly
+     */
+    private MavenProject project;
+
+
+    /**
+     * The goal prefix that will appear before the ":".
+     *
+     * @parameter expression="${goalPrefix}"
+     * @since 2.4
+     */
+    protected String goalPrefix;
+
+    /**
+     * Set this to "true" to skip invoking any goals or reports of the plugin.
+     *
+     * @parameter default-value="false" expression="${maven.plugin.skip}"
+     * @since 2.8
+     */
+    private boolean skip;
+
+    /**
+     * Set this to "true" to skip generating the report.
+     *
+     * @parameter default-value="false" expression="${maven.plugin.report.skip}"
+     * @since 2.8
+     */
+    private boolean skipReport;
+
+    /** {@inheritDoc} */
+    protected Renderer getSiteRenderer()
+    {
+        return siteRenderer;
+    }
+
+    /** {@inheritDoc} */
+    protected String getOutputDirectory()
+    {
+        return outputDirectory.getPath();
+    }
+
+    /** {@inheritDoc} */
+    protected MavenProject getProject()
+    {
+        return project;
+    }
+
+    /** {@inheritDoc} */
+    public boolean canGenerateReport()
+    {
+        return true;
+    }
+
+    /** {@inheritDoc} */
+    protected void executeReport( Locale locale )
+        throws MavenReportException
+    {
+        if ( !canGenerateReport() )
+        {
+            return;
+        }
+        if (skip || skipReport)
+        {
+            getLog().info( "Maven Plugin Plugin Report generation skipped." );
+            return;
+        }
+
+        // Generate the plugin's documentation
+        generatePluginDocumentation( locale );
+    }
+
+    /** {@inheritDoc} */
+    public String getDescription( Locale locale )
+    {
+        return getBundle( locale ).getString( "report.plugin.description" );
+    }
+
+    /** {@inheritDoc} */
+    public String getName( Locale locale )
+    {
+        return getBundle( locale ).getString( "report.plugin.name" );
+    }
+
+    /** {@inheritDoc} */
+    public String getOutputName()
+    {
+        return "plugin-info";
+    }
+
+    /**
+     * @param pluginDescriptor not null
+     * @param locale not null
+     * @throws MavenReportException if any
+     */
+    private void generatePluginDocumentation( Locale locale )
+        throws MavenReportException
+    {
+        File outputDir = new File( getOutputDirectory() );
+        outputDir.mkdirs();
+        PluginOverviewRenderer r = new PluginOverviewRenderer( getSink(), locale );
+        r.render();
+    }
+
+    /**
+     * @param locale not null
+     * @return the bundle for this report
+     */
+    protected static ResourceBundle getBundle( Locale locale )
+    {
+        return ResourceBundle.getBundle( "plugin-report", locale, DummyReport.class.getClassLoader() );
+    }
+
+    /**
+     * Generates an overview page with the list of goals
+     * and a link to the goal's page.
+     */
+    static class PluginOverviewRenderer
+        extends AbstractMavenReportRenderer
+    {
+        private final Locale locale;
+
+        /**
+         * @param project not null
+         * @param sink not null
+         * @param locale not null
+         */
+        public PluginOverviewRenderer( Sink sink,
+                                       Locale locale )
+        {
+            super( sink );
+
+            this.locale = locale;
+        }
+
+        /** {@inheritDoc} */
+        public String getTitle()
+        {
+            return getBundle( locale ).getString( "report.plugin.title" );
+        }
+
+        /** {@inheritDoc} */
+        public void renderBody()
+        {
+            startSection( getTitle() );
+            paragraph( "This is a report." );
+            endSection();
+        }
+    }
+}

maven-plugin-plugin/src/it/plugin-report/src/main/java/org/MyMojo.java

@@ -46,6 +46,7 @@ public class MyMojo
      * @parameter
      * @required
      */
+    @SuppressWarnings( "unused" )
     private String required;
 
     /**
@@ -55,6 +56,7 @@ public class MyMojo
      * @deprecated Just testing.
      * @since 1.1
      */
+    @SuppressWarnings( "unused" )
     private String string;
 
     public void execute()

maven-plugin-plugin/src/it/plugin-report/verify.bsh

@@ -14,7 +14,8 @@ try
 
     String[] expectedFiles = {
         "noop-mojo.html",
-        "plugin-info.html",
+        "noop-mojo.html",
+        "report-mojo.html",
     };
     for ( String path : expectedFiles )
     {

maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java

@@ -337,6 +337,7 @@ public class PluginReport
         }
 
         /** {@inheritDoc} */
+        @SuppressWarnings( { "unchecked", "rawtypes" } )
         public void renderBody()
         {
             startSection( getTitle() );
@@ -352,8 +353,7 @@ public class PluginReport
 
 
             boolean hasMavenReport = false;
-            for ( @SuppressWarnings( "unchecked" )
+            for ( Iterator<MojoDescriptor> i = pluginDescriptor.getMojos().iterator(); i.hasNext(); )
-            Iterator<MojoDescriptor> i = pluginDescriptor.getMojos().iterator(); i.hasNext(); )
             {
                 MojoDescriptor mojo = i.next();
 
@@ -626,6 +626,7 @@ public class PluginReport
          * @param pluginsAsMap could be null
          * @return the value of the <code>target</code> in the configuration of <code>maven-compiler-plugin</code>.
          */
+        @SuppressWarnings( "rawtypes" )
         private static String discoverJdkRequirementFromPlugins( Map pluginsAsMap )
         {
             if ( pluginsAsMap == null )

maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java

@@ -273,6 +273,18 @@ public class PluginXdocGenerator
             w.writeMarkup( getString( "pluginxdoc.mojodescriptor.projectRequired" ) );
             w.endElement(); //li
         }
+        
+        if ( mojoDescriptor.isRequiresReports() )
+        {
+            if ( !addedUl )
+            {
+                w.startElement(  "ul" );
+                addedUl = true;
+            }
+            w.startElement( "li" );
+            w.writeMarkup( getString( "pluginxdoc.mojodescriptor.reportingMojo" ) );
+            w.endElement(); // li
+        }
 
         if ( mojoDescriptor.isAggregator() )
         {

maven-plugin-tools-api/src/main/resources/pluginxdoc.properties

@@ -29,6 +29,7 @@ pluginxdoc.mojodescriptor.deprecated=<strong>This plugin goal has been deprecate
 pluginxdoc.mojodescriptor.projectRequired=Requires a Maven project to be executed.
 pluginxdoc.mojodescriptor.aggregator=Executes as an aggregator plugin.
 pluginxdoc.mojodescriptor.directInvocationOnly=Executes by direct invocation only.
+pluginxdoc.mojodescriptor.reportingMojo=Executes as a reportSet (reporting goal).
 pluginxdoc.mojodescriptor.dependencyResolutionRequired=Requires dependency resolution of artifacts in scope: <code>{0}</code>.
 pluginxdoc.mojodescriptor.dependencyCollectionRequired=Requires dependency collection of artifacts in scope: <code>{0}</code>.
 pluginxdoc.mojodescriptor.since=Since version: <code>{0}</code>.

maven-plugin-tools-api/src/main/resources/pluginxdoc_fr.properties

@@ -29,6 +29,7 @@ pluginxdoc.mojodescriptor.deprecated=<strong>Le goal de ce plugin goal est obsol
 pluginxdoc.mojodescriptor.projectRequired=Exige un projet Maven pour \u00eatre ex\u00e9cut\u00e9.
 pluginxdoc.mojodescriptor.aggregator=S'ex\u00e9cute comme un plugin agr\u00e9g\u00e9.
 pluginxdoc.mojodescriptor.directInvocationOnly=S'ex\u00e9cute par l'invocation directe seulement.
+pluginxdoc.mojodescriptor.reportingMojo=S'ex\u00e9cute comme un reportSet (goal de reportage).
 pluginxdoc.mojodescriptor.dependencyResolutionRequired=Exige une r\u00e9solution de d\u00e9pendances des artefacts dans le scope : <code>{0}</code>.
 pluginxdoc.mojodescriptor.dependencyCollectionRequired=Exige une collection de d\u00e9pendances des artefacts dans le scope : <code>{0}</code>.
 pluginxdoc.mojodescriptor.since=Depuis la version : <code>{0}</code>.