svn commit: r1466309 - in /maven/plugins/trunk/maven-site-plugin/src: main/java/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.java site/apt/maven-3.apt.vm

[hb...@apache.org]

Author: hboutemy
Date: Wed Apr 10 01:24:55 2013
New Revision: 1466309

URL: http://svn.apache.org/r1466309
Log:
[MSITE-684] mark reportPlugins parameter as read-only, hiding it from generated goal documentation (but not enforcing it won't be used because Maven 3 doesn't check: see MNG-5001)

Modified:
    maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.java
    maven/plugins/trunk/maven-site-plugin/src/site/apt/maven-3.apt.vm

Modified: maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.java?rev=1466309&r1=1466308&r2=1466309&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.java (original)
+++ maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/AbstractSiteRenderingMojo.java Wed Apr 10 01:24:55 2013
@@ -170,7 +170,7 @@ public abstract class AbstractSiteRender
     protected MavenSession mavenSession;
 
     /**
-     * <p>Configuration section used internally by Maven 3.</p>
+     * <p>Configuration section <b>used internally</b> by Maven 3.</p>
      * <p>More details available here:
      * <a href="http://maven.apache.org/plugins/maven-site-plugin/maven-3.html#Configuration_formats" target="_blank">
      * http://maven.apache.org/plugins/maven-site-plugin/maven-3.html#Configuration_formats</a>
@@ -178,9 +178,9 @@ public abstract class AbstractSiteRender
      * <p><b>Note:</b> using this field is not mandatory with Maven 3 as Maven core injects usual
      * <code>&lt;reporting&gt;</code> section into this field.</p>
      *
-     * @since 3.0-beta-1
+     * @since 3.0-beta-1 (and read-only since 3.3)
      */
-    @Parameter
+    @Parameter( readonly = true )
     private ReportPlugin[] reportPlugins;
 
     private PlexusContainer container;

Modified: maven/plugins/trunk/maven-site-plugin/src/site/apt/maven-3.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/maven-3.apt.vm?rev=1466309&r1=1466308&r2=1466309&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/maven-3.apt.vm (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/maven-3.apt.vm Wed Apr 10 01:24:55 2013
@@ -289,13 +289,22 @@ Using it with Maven 3
 
 ** New Configuration (Maven 3 only, no reports configuration inheritance)
 
-  Reports can be configured in the configuration of <<<maven-site-plugin>>> as <<<\<reportPlugins\>>>> elements.
+  Starting with <<<maven-site-plugin>>> 3.0, reports could be configured in the configuration of <<<maven-site-plugin>>>
+  as <<<\<reportPlugins\>>>> elements.
   
   <<This new configuration format is not actually ready for end-users: please don't use it for the moment.>>
 
-  <Explanation:> The new format does not actually support report plugins configuration inheritance, which is crucial for
-  usability: see {{{http://jira.codehaus.org/browse/MSITE-484}MSITE-484}}. This format was technically necessary to remove
-  most reporting logic from Maven 3, but a new inheritance mechanism still needs to be added to make it as flexible as the old format.
+  As a consequence, with <<<maven-site-plugin>>> 3.3, the <<<\<reportPlugins\>>>> configuration has simply been removed
+  (more precisely marked private/internal), since it should not be used directly. This documentation has been kept
+  public only to help people who used it in previous versions understand why they need to migrate back to classic configuration.
+
+  <Explanation:> The (former) new format did not support report plugins configuration inheritance, which is crucial for
+  usability: see {{{http://jira.codehaus.org/browse/MSITE-484}MSITE-484}}. This field is technically necessary to remove
+  most reporting logic from Maven 3, but a new inheritance mechanism still needs to be added to make it as flexible as the old format:
+  we made the field public before finding this crucial limitation and required to explain later why end-users must not use it, then
+  cannot use it since <<<maven-site-plugin>>> 3.3.
+
+  Here is how this feature looked like:
 
 +-----+
   <build>
@@ -303,10 +312,10 @@ Using it with Maven 3
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-site-plugin</artifactId>
-        <version>${project.version}</version>
+        <version>3.2</version><!-- last maven-site-plugin version supporting this reportPlugins configuration -->
         <configuration>
           ...
-          <reportPlugins>
+          <reportPlugins><!-- not supported any more... (now kept internal) -->
             <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-project-info-reports-plugin</artifactId>