Added methods to repeat arguments (for group, tag, link and linkoffline options provided by the Javadoc standard doclet). Added plexus-utils as transitive dep.

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

maven-plugins/maven-javadoc-plugin/pom.xml

@@ -40,6 +40,10 @@
       <artifactId>commons-lang</artifactId>
       <version>2.1</version>
     </dependency>
+    <dependency>
+      <groupId>plexus</groupId>
+      <artifactId>plexus-utils</artifactId>
+    </dependency>
   </dependencies>
   <developers>
     <developer>

maven-plugins/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java

@@ -26,7 +26,6 @@ import java.util.Locale;
 import java.util.StringTokenizer;
 
 import org.apache.commons.lang.ClassUtils;
-import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.SystemUtils;
 import org.apache.commons.lang.math.NumberUtils;
 import org.apache.maven.project.MavenProject;
@@ -37,6 +36,7 @@ import org.codehaus.doxia.sink.Sink;
 import org.codehaus.doxia.site.renderer.SiteRenderer;
 import org.codehaus.plexus.util.FileUtils;
 import org.codehaus.plexus.util.IOUtil;
+import org.codehaus.plexus.util.StringUtils;
 import org.codehaus.plexus.util.cli.CommandLineUtils;
 import org.codehaus.plexus.util.cli.Commandline;
 import org.codehaus.plexus.util.cli.DefaultConsumer;
@@ -60,21 +60,26 @@ public class JavadocReport
     extends AbstractMavenReport
 {
     /** The current class directory */
-    private static final String RESOURCE_DIR = ClassUtils.getPackageName(JavadocReport.class).replace('.', '/');
+    private static final String RESOURCE_DIR = ClassUtils.getPackageName( JavadocReport.class ).replace( '.', '/' );
 
     /** Default location for css */
     private static final String DEFAULT_CSS_NAME = "stylesheet.css";
+
     private static final String RESOURCE_CSS_DIR = RESOURCE_DIR + "/css";
 
     // Using for the plugin:xdoc goal. Best way?
     /** Default bottom */
     private static final String DEFAULT_BOTTOM = "Copyright ${project.inceptionYear-currentYear} ${project.organization.name}. All Rights Reserved.";
+
     /** Default bottom */
     private static final String DEFAULT_DESTDIR = "${project.build.directory}/site/apidocs";
+
     /** Default doctitle */
     private static final String DEFAULT_DOCTITLE = "${windowtitle}";
+
     /** Default organization name */
     private static final String DEFAULT_ORGANIZATION_NAME = "The Apache Software Foundation";
+
     /** Default window title */
     private static final String DEFAULT_WINDOW_TITLE = "${project.name} ${project.version} API";
 
@@ -342,6 +347,7 @@ public class JavadocReport
     /**
      * Separates packages on the overview page into whatever groups you specify, one group per table.
      * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#group">group</a>.
+     * It is a comma separated String.
      * 
      * @parameter expression="${group}"
      */
@@ -366,6 +372,7 @@ public class JavadocReport
     /**
      * Creates links to existing javadoc-generated documentation of external referenced classes.
      * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#link">link</a>.
+     * It is a comma separated String.
      * 
      * @parameter expression="${link}"
      */
@@ -374,6 +381,7 @@ public class JavadocReport
     /**
      * This option is a variation of -link; they both create links to javadoc-generated documentation for external referenced classes.
      * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#linkoffline">linkoffline</a>.
+     * It is a comma separated String.
      * 
      * @parameter expression="${linkoffline}"
      */
@@ -399,7 +407,7 @@ public class JavadocReport
 
     /**
      * Prevents the generation of any deprecated API at all in the documentation.
-     * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#linksource">nodeprecated</a>.
+     * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#nodeprecated">nodeprecated</a>.
      * 
      * @parameter expression="${nodeprecated}"
      * default-value="false"
@@ -498,6 +506,7 @@ public class JavadocReport
     /**
      * Enables the Javadoc tool to interpret a simple, one-argument custom block tag tagname in doc comments.
      * See <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#tag">tag</a>.
+     * It is a comma separated String.
      * 
      * @parameter expression="${tag}"
      */
@@ -546,6 +555,7 @@ public class JavadocReport
      * default-value="${project.name} ${project.version} API"
      */
     private String windowtitle;
+
     // End JavaDoc parameters
 
     /** The command line built to execute Javadoc. */
@@ -690,15 +700,16 @@ public class JavadocReport
                 }
                 else
                 {
-                    if ( ( NumberUtils.isDigits( this.maxmemory.substring( 0, this.maxmemory.length() - 1) ) ) 
+                    if ( ( NumberUtils.isDigits( this.maxmemory.substring( 0, this.maxmemory.length() - 1 ) ) )
                         && ( this.maxmemory.toLowerCase().endsWith( "m" ) ) )
                     {
-
                         addArgIf( true, "-J-Xmx" + this.maxmemory );
                     }
                     else
                     {
-                        getLog().error( "The maxmemory '" + this.maxmemory + "' is not a valid number. Ignore this option." );
+                        getLog().error(
+                                        "The maxmemory '" + this.maxmemory
+                                            + "' is not a valid number. Ignore this option." );
                     }
                 }
             }
@@ -711,15 +722,16 @@ public class JavadocReport
                 }
                 else
                 {
-                    if ( ( NumberUtils.isDigits( this.minmemory.substring( 0, this.minmemory.length() - 1) ) ) 
+                    if ( ( NumberUtils.isDigits( this.minmemory.substring( 0, this.minmemory.length() - 1 ) ) )
                         && ( this.minmemory.toLowerCase().endsWith( "m" ) ) )
                     {
-
                         addArgIf( true, "-J-Xms" + this.minmemory );
                     }
                     else
                     {
-                        getLog().error( "The minmemory '" + this.minmemory + "' is not a valid number. Ignore this option." );
+                        getLog().error(
+                                        "The minmemory '" + this.minmemory
+                                            + "' is not a valid number. Ignore this option." );
                     }
                 }
             }
@@ -752,7 +764,8 @@ public class JavadocReport
                 {
                     this.bottom = "Copyright &copy; " + year + " ";
 
-                    if ( ( model.getOrganization() != null ) && ( !StringUtils.isEmpty( model.getOrganization().getName() ) ) )
+                    if ( ( model.getOrganization() != null )
+                        && ( !StringUtils.isEmpty( model.getOrganization().getName() ) ) )
                     {
                         this.bottom += model.getOrganization().getName();
                     }
@@ -794,11 +807,11 @@ public class JavadocReport
                 addArgIfNotEmpty( "-excludePackageNames", this.excludePackageNames );
                 addArgIfNotEmpty( "-excludedocfilessubdir", this.excludedocfilessubdir, 1.4f );
                 addArgIfNotEmpty( "-footer", this.footer );
-                addArgIfNotEmpty( "-group", this.group );
+                addArgIfNotEmpty( "-group", this.group, true );
                 addArgIfNotEmpty( "-header", this.header );
                 addArgIfNotEmpty( "-helpfile", this.helpfile );
-                addArgIfNotEmpty( "-link", this.link );
+                addArgIfNotEmpty( "-link", this.link, true );
-                addArgIfNotEmpty( "-linkoffline", this.linkoffline );
+                addArgIfNotEmpty( "-linkoffline", this.linkoffline, true );
                 addArgIf( this.linksource, "-linksource", 1.4f );
                 addArgIf( this.nodeprecated, "-nodeprecated" );
                 addArgIf( this.nodeprecatedlist, "-nodeprecatedlist" );
@@ -812,7 +825,7 @@ public class JavadocReport
                 addArgIf( this.serialwarn, "-serialwarn" );
                 addArgIf( this.splitindex, "-splitindex" );
                 addArgIfNotEmpty( "-stylesheetfile", this.stylesheetfile );
-                addArgIfNotEmpty( "-tag", this.tag, 1.4f );
+                addArgIfNotEmpty( "-tag", this.tag, 1.4f, true );
                 addArgIfNotEmpty( "-taglet", this.taglet, 1.4f );
                 addArgIfNotEmpty( "-tagletpath", this.tagletpath, 1.4f );
                 addArgIf( this.use, "-use" );
@@ -824,7 +837,8 @@ public class JavadocReport
 
             getLog().info( Commandline.toString( cmd.getCommandline() ) );
 
-            final int exitCode = CommandLineUtils.executeCommandLine( cmd, new DefaultConsumer(), new DefaultConsumer() );
+            final int exitCode = CommandLineUtils
+                .executeCommandLine( cmd, new DefaultConsumer(), new DefaultConsumer() );
             if ( exitCode != 0 )
             {
                 throw new MavenReportException( "Exit code: " + exitCode );
@@ -854,8 +868,10 @@ public class JavadocReport
     {
         final String javadocCommand = "javadoc" + ( SystemUtils.IS_OS_WINDOWS ? ".exe" : "" );
         // For IBM's JDK 1.2
-        final File javadocExe = ( SystemUtils.IS_OS_AIX ? new File( SystemUtils.getJavaHome() + "/../sh", javadocCommand )
+        final File javadocExe = ( SystemUtils.IS_OS_AIX ? new File( SystemUtils.getJavaHome() + "/../sh",
-                                                  : new File( SystemUtils.getJavaHome() + "/../bin", javadocCommand ) );
+                                                                    javadocCommand ) : new File( SystemUtils
+            .getJavaHome()
+            + "/../bin", javadocCommand ) );
 
         getLog().debug( "Javadoc executable=[" + javadocExe.getAbsolutePath() + "]" );
 
@@ -906,10 +922,27 @@ public class JavadocReport
      * <p>
      * Moreover, the value could be comma separated.
      * 
+     * @see #addArgIfNotEmpty(String, String, boolean)
+     * 
      * @param key the argument name.
      * @param value the argument value to be added.
      */
     private void addArgIfNotEmpty( final String key, final String value )
+    {
+        addArgIfNotEmpty( key, value, false );
+    }
+
+    /**
+     * Convenience method to add an argument to the <code>command line</code>
+     * if the the value is not null or empty.
+     * <p>
+     * Moreover, the value could be comma separated.
+     * 
+     * @param key the argument name.
+     * @param value the argument value to be added.
+     * @param repeatKey repeat or not the key in the command line
+     */
+    private void addArgIfNotEmpty( final String key, final String value, final boolean repeatKey )
     {
         if ( !StringUtils.isEmpty( value ) )
         {
@@ -919,10 +952,34 @@ public class JavadocReport
             while ( token.hasMoreTokens() )
             {
                 String current = token.nextToken().trim();
+
+                if ( !StringUtils.isEmpty( current ) )
+                {
                     this.cmd.createArgument().setValue( current );
+
+                    if ( token.hasMoreTokens() && repeatKey )
+                    {
+                        this.cmd.createArgument().setValue( key );
                     }
                 }
             }
+        }
+    }
+
+    /**
+     * Convenience method to add an argument to the <code>command line</code>
+     * regarding the requested Java version.
+     * 
+     * @see #addArgIfNotEmpty(String, String, float, boolean)
+     * 
+     * @param key the argument name.
+     * @param value the argument value to be added.
+     * @param requiredJavaVersion the required Java version, for example 1.31f or 1.4f
+     */
+    private void addArgIfNotEmpty( final String key, final String value, final float requiredJavaVersion )
+    {
+        addArgIfNotEmpty( key, value, requiredJavaVersion, false );
+    }
 
     /**
      * Convenience method to add an argument to the <code>command line</code>
@@ -931,18 +988,17 @@ public class JavadocReport
      * @see #addArgIfNotEmpty(String, String)
      * @see <a href="http://jakarta.apache.org/commons/lang/api/org/apache/commons/lang/SystemUtils.html#isJavaVersionAtLeast(float)">SystemUtils.html#isJavaVersionAtLeast(float)</a>
      * 
-     * @param key
+     * @param key the argument name.
-     *            the argument name.
+     * @param value the argument value to be added.
-     * @param value
+     * @param requiredJavaVersion the required Java version, for example 1.31f or 1.4f
-     *            the argument value to be added.
+     * @param repeatKey repeat or not the key in the command line
-     * @param requiredJavaVersion  
-     *            the required Java version, for example 1.31f or 1.4f
      */
-    private void addArgIfNotEmpty( final String key, final String value, final float requiredJavaVersion )
+    private void addArgIfNotEmpty( final String key, final String value, final float requiredJavaVersion,
+                                  final boolean repeatKey )
     {
         if ( SystemUtils.isJavaVersionAtLeast( requiredJavaVersion ) )
         {
-            addArgIfNotEmpty( key, value );
+            addArgIfNotEmpty( key, value, repeatKey );
         }
         else
         {

maven-plugins/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/pom.xml

@@ -55,6 +55,10 @@
           <minmemory>128m</minmemory>
           <maxmemory>512</maxmemory>
           <bottom>Copyright me</bottom>
+          <source>true</source>
+          <link>http://java.sun.com/j2se/1.4.2/docs/api, http://maven.apache.org/apidocs/</link>
+          <group>"Core Packages" "org.apache.maven.plugin.javadoc.test1", "Extension Packages" "org.apache.maven.plugin.javadoc.test2"</group>
+          <tag>.usage:a:Usage:, .todo:a:To do something:, .fixme:a:Fixme:</tag>
         </configuration>
       </plugin>
     </plugins>

maven-plugins/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/src/main/java/org/apache/maven/plugin/javadoc/test1/App.java

@@ -6,6 +6,16 @@ package org.apache.maven.plugin.javadoc.test1;
  */
 public class App 
 {
+    /**
+     * @.todo to do 
+     * @.usage usage is java org.apache.maven.plugin.javadoc.test1.App
+     * @.fixme Fix me!
+     * 
+     * @see System#out
+     * @see org.apache.maven.MavenException
+     * 
+     * @param args
+     */
     public static void main( String[] args )
     {
         System.out.println( "Hello World!" );