[NOJIRA] Javadoc cleanup in preparation of release

Closes #85.

src/main/java/org/apache/maven/shared/utils/Os.java

@@ -26,12 +26,10 @@
 
 /**
  * <p>Condition that tests the OS type.</p>
- * <p/>
  * <p>This class got copied over from Apache ANT.
  * Even the version from plexus-utils was
- * only an ANT fork!<br/>
+ * only an ANT fork!
  * The last time it got copied was on 2011-08-12</p>
- * <p/>
  * <p>When merging changes please take care of the special
  * OS_FAMILY handling in this version of Os.java!</p>
  *

src/main/java/org/apache/maven/shared/utils/PathTool.java

@@ -26,12 +26,13 @@
 import javax.annotation.Nullable;
 
 /**
- * Path tool contains static methods to assist in determining path-related
- * information such as relative paths.
- * <p/>
+ * <p>Path tool contains static methods to assist in determining path-related
+ * information such as relative paths.</p>
+ * <p>
  * This class originally got developed at Apache Anakia and later maintained
  * in maven-utils of Apache Maven-1.
  * Some external fixes by Apache Committers have been applied later.
+ * </p>
  */
 public class PathTool
 {
@@ -55,9 +56,9 @@ public PathTool()
      * file separators.  The relative path returned is formed using
      * forward slashes as it is expected this path is to be used as a
      * link in a web page (again mimicking Anakia's behavior).
-     * <p/>
+     * <p>
      * This method is thread-safe.
-     * <br/>
+     * </p>
      * <pre>
      * PathTool.getRelativePath( null, null )                                   = ""
      * PathTool.getRelativePath( null, "/usr/local/java/bin" )                  = ""
@@ -111,8 +112,7 @@ public static String getRelativePath( @Nullable String basedir, @Nullable String
     }
 
     /**
-     * This method can calculate the relative path between two pathes on a file system.
-     * <br/>
+     * <p>This method can calculate the relative path between two paths on a file system.</p>
      * <pre>
      * PathTool.getRelativeFilePath( null, null )                                   = ""
      * PathTool.getRelativeFilePath( null, "/usr/local/java/bin" )                  = ""

src/main/java/org/apache/maven/shared/utils/StringUtils.java

@@ -104,7 +104,6 @@ public static String trim( String str )
      *
      * @param str String target to delete whitespace from
      * @return the String without whitespace
-     * @throws NullPointerException
      */
     @Nonnull public static String deleteWhitespace( @Nonnull String str )
     {
@@ -122,7 +121,7 @@ public static String trim( String str )
 
     /**
      * <p>Checks if a String is non <code>null</code> and is
-     * not empty (<code>length > 0</code>).</p>
+     * not empty (<code>length &gt; 0</code>).</p>
      *
      * @param str the String to check
      * @return true if the String is non-null, and not length zero
@@ -816,7 +815,7 @@ public static String replace( @Nullable String text, @Nullable String repl, @Nul
     //--------------------------------------------------------------------------
 
     /**
-     * <p>Center a String in a larger String of size <code>n</code>.<p>
+     * <p>Center a String in a larger String of size <code>n</code>.</p>
      *
      * <p>Uses spaces as the value to buffer the String with.
      * Equivalent to <code>center(str, size, " ")</code>.</p>
@@ -1174,7 +1173,7 @@ else if ( ch < 32 )
      * @param str    String to repeat
      * @param repeat number of times to repeat str
      * @return String with repeated String
-     * @throws NegativeArraySizeException if <code>repeat < 0</code>
+     * @throws NegativeArraySizeException if <code>repeat &lt; 0</code>
      * @throws NullPointerException       if str is <code>null</code>
      */
     @Nonnull public static String repeat( @Nonnull String str, int repeat )
@@ -1979,14 +1978,12 @@ private static void reverseArray( @Nonnull String... array )
     //--------------------------------------------------------------------------
 
     /**
-     * Turn "Now is the time for all good men" into "Now is the time for..."
-     * <p/>
-     * Specifically:
-     * <p/>
-     * If str is less than max characters long, return it.
+     * <p>Turn "Now is the time for all good men" into "Now is the time for..."</p>
+     * <p>Specifically:</p>
+     * <p>If str is less than max characters long, return it.
      * Else abbreviate it to (substring(str, 0, max-3) + "...").
      * If maxWidth is less than 3, throw an IllegalArgumentException.
-     * In no case will it return a string of length greater than maxWidth.
+     * In no case will it return a string of length greater than maxWidth.</p>
      * 
      * @param s The string to be abbreviated.
      * @param maxWidth maximum length of result string
@@ -1999,12 +1996,13 @@ private static void reverseArray( @Nonnull String... array )
 
     /**
      * Turn "Now is the time for all good men" into "...is the time for..."
-     * <p/>
+     * <p>
      * Works like abbreviate(String, int), but allows you to specify a "left edge"
      * offset.  Note that this left edge is not necessarily going to be the leftmost
      * character in the result, or the first
      * character following the ellipses, but it will appear somewhere in the result.
      * In no case will it return a string of length greater than maxWidth.
+     * </p>
      * 
      * @param s        String to abbreviate.
      * @param offset   left edge of source string
@@ -2051,8 +2049,9 @@ private static void reverseArray( @Nonnull String... array )
      * Compare two strings, and return the portion where they differ.
      * (More precisely, return the remainder of the second string,
      * starting from where it's different from the first.)
-     * <p/>
-     * E.g. strdiff("i am a machine", "i am a robot") -> "robot"
+     * <p>
+     * E.g. strdiff("i am a machine", "i am a robot") &rarr; "robot"
+     * </p>
      *
      * @param s1 The first string.
      * @param s2 The second string.
@@ -2071,7 +2070,7 @@ public static String difference( @Nonnull String s1, @Nonnull String s2 )
     /**
      * Compare two strings, and return the index at which the strings begin to differ.
      * <p>
-     * E.g. strdiff("i am a machine", "i am a robot") -> 7
+     * E.g. strdiff("i am a machine", "i am a robot") &rarr; 7
      * </p>
      *
      * @param s1 The first string.
@@ -2188,7 +2187,6 @@ public static String interpolate( String text, @Nonnull Map<?, ?> namespace )
     /**
      * Converts the first character of the given String to lowercase.
      * This method does <i>not</i> trim spaces!
-     * <p/>
      *
      * @param data the String to get it's first character lower-cased.
      * @return data string with the first character transformed to lowercase
@@ -2205,9 +2203,8 @@ public static String interpolate( String text, @Nonnull Map<?, ?> namespace )
     }
 
     /**
-     * Take the input string and un-camel-case it.
-     * <p/>
-     * 'ThisIsIt' will become 'this-is-it'.
+     * <p>Take the input string and un-camel-case it.</p>
+     * <p>'ThisIsIt' will become 'this-is-it'.</p>
      *
      * @param view the view
      * @return deHumped String
@@ -2519,7 +2516,6 @@ public static boolean contains( @Nullable String str, @Nullable String searchStr
 
     /**
      * <p>Checks if String ends with a search String, handling <code>null</code>.</p>
-     * <p/>
      * <p>A <code>null</code> String will return <code>false</code>.</p>
      *
      * <pre>

src/main/java/org/apache/maven/shared/utils/cli/Arg.java

@@ -33,6 +33,7 @@ public interface Arg
 
     /**
      * @param line the line of arguments
+     * @throws CommandLineException in case of unbalanced quotes.
      */
     void setLine( String line ) throws CommandLineException;
 

src/main/java/org/apache/maven/shared/utils/cli/Commandline.java

@@ -37,15 +37,14 @@
 import org.apache.maven.shared.utils.cli.shell.Shell;
 
 /**
- * <p/>
+ * <p>
  * Commandline objects help handling command lines specifying processes to
  * execute.
  * </p>
- * <p/>
+ * <p>
  * The class can be used to define a command line as nested elements or as a
  * helper to define a command line by an application.
  * </p>
- * <p/>
  * <code>
  * &lt;someelement&gt;<br>
  * &nbsp;&nbsp;&lt;acommandline executable="/executable/to/run"&gt;<br>
@@ -55,8 +54,7 @@
  * &nbsp;&nbsp;&lt;/acommandline&gt;<br>
  * &lt;/someelement&gt;<br>
  * </code>
- * </p>
- * <p/>
+ * <p>
  * The element <code>someelement</code> must provide a method
  * <code>createAcommandline</code> which returns an instance of this class.
  * </p>
@@ -89,6 +87,7 @@ public Commandline( Shell shell )
      * Shell is autodetected from operating system.
      *
      * @param toProcess the command to process
+     * @throws CommandLineException in case of unbalanced quotes.
      */
     public Commandline( String toProcess ) throws CommandLineException
     {

src/main/java/org/apache/maven/shared/utils/cli/StreamConsumer.java

@@ -22,12 +22,11 @@
 import java.io.IOException;
 
 /**
- * Works in concert with the StreamPumper class to
+ * <p>Works in concert with the StreamPumper class to
  * allow implementations to gain access to the lines being
- * "Pumped".
- * <p/>
- * Please note that implementations of this interface can be expected to be
- * called from arbitrary threads and must therefore be threadsafe.
+ * "Pumped".</p>
+ * <p>Please note that implementations of this interface can be expected to be
+ * called from arbitrary threads and must therefore be threadsafe.</p>
  *
  * @author <a href="mailto:fvancea@maxiq.com">Florin Vancea</a>
  * @author <a href="mailto:pj@thoughtworks.com">Paul Julius</a>

src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaTool.java

@@ -36,9 +36,9 @@
 /**
  * Abstract implementation of a {@link JavaTool}.
  *
- * @author Tony Chemit <chemit@codelutin.com>
+ * @author <a href="mailto:chemit@codelutin.com">Tony Chemit</a>
  * @since 0.5
- * @param <Request>
+ * @param <Request> Tool-specific request type
  */
 public abstract class AbstractJavaTool<Request extends JavaToolRequest>
     extends AbstractLogEnabled

src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaToolRequest.java

@@ -24,7 +24,7 @@
 /**
  * Abstract implementation of a {@link JavaToolRequest}.
  *
- * @author Tony Chemit <chemit@codelutin.com>
+ * @author <a href="mailto:chemit@codelutin.com">Tony Chemit</a>
  * @since 0.5
  */
 public class AbstractJavaToolRequest

src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java

@@ -20,26 +20,23 @@
  */
 
 /**
- * Describes a java tool, means a executable available in the jdk.
- * <p/>
- * The name of the tool ({@link #getJavaToolName()}) reflects the name of the executable that should exists as an
- * executable in the jdk, like {@code jarsigner, keytool, javadoc, ...}.
- * <p/>
- * An abstract implementation of the {@link JavaTool} named {@link AbstractJavaTool} use the command line API to execute
- * any user requests of this tool.
+ * <p>Describes a java tool, means a executable available in the jdk.</p>
+ * <p>The name of the tool ({@link #getJavaToolName()}) reflects the name of the executable that should exists as an
+ * executable in the jdk, like {@code jarsigner, keytool, javadoc, ...}.</p>
+ * <p>An abstract implementation of the {@link JavaTool} named {@link AbstractJavaTool} use the command line API to
+ * execute any user requests of this tool.</p>
  *
- * @author Tony Chemit <chemit@codelutin.com>
+ * @author <a href="mailto:chemit@codelutin.com">Tony Chemit</a>
  * @since 0.5
- * @param <Request>
+ * @param <Request> Tool-specific request type
  */
 public interface JavaTool<Request extends JavaToolRequest>
 {
 
     /**
-     * Return the name of the java tool. This is exactly the name (without his extension) of the executable to
-     * find in the {@code jdk/bin} directory.
-     * <p/>
-     * For example: {@code jarsigner, keytool, javadoc, ...}
+     * <p>Return the name of the java tool. This is exactly the name (without his extension) of the executable to
+     * find in the {@code jdk/bin} directory.</p>
+     * <p>For example: {@code jarsigner, keytool, javadoc, ...}</p>
      *
      * @return the name of the java tool.
      */
@@ -55,13 +52,11 @@ public interface JavaTool<Request extends JavaToolRequest>
     void setToolchain( Object toolchain );
 
     /**
-     * Execute the input request and then returns the result of the execution.
-     * <p/>
-     * If could not create the java tool invocation, a {@link JavaToolException} will be thrown.
-     * <p/>
-     * If execution fails, then the result will have a none-zero {@link JavaToolResult#getExitCode()} and his
+     * <p>Execute the input request and then returns the result of the execution.</p>
+     * <p>If could not create the java tool invocation, a {@link JavaToolException} will be thrown.</p>
+     * <p>If execution fails, then the result will have a none-zero {@link JavaToolResult#getExitCode()} and his
      * {@link JavaToolResult#getExecutionException()} will be filled with the error, otherwise the exist code will be
-     * zero.
+     * zero.</p>
      *
      * @param request the request to perform
      * @return the result of the tool execution

src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java

@@ -20,13 +20,12 @@
  */
 
 /**
- * Signals an error during the construction of the command line used to invoke java tool, e.g. illegal invocation
- * arguments.
- * <p/>
- * This should not be confused with a failure of the invoked java tool build itself which will be reported by means of a
- * non-zero exit code.
+ * <p>Signals an error during the construction of the command line used to invoke java tool, e.g. illegal invocation
+ * arguments.</p>
+ * <p>This should not be confused with a failure of the invoked java tool build itself which will be reported by means
+ * of a non-zero exit code.</p>
  *
- * @author Tony Chemit <chemit@codelutin.com>
+ * @author <a href="mailto:chemit@codelutin.com">Tony Chemit</a>
  *
  * @see JavaToolResult#getExitCode()
  * @since 0.5

src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolRequest.java

@@ -24,27 +24,25 @@
 /**
  * Specifies the minimum parameters used to control a {@link JavaTool} invocation.
  *
- * @author Tony Chemit <chemit@codelutin.com>
+ * @author <a href="mailto:chemit@codelutin.com">Tony Chemit</a>
  * @since 0.5
  */
 public interface JavaToolRequest
 {
 
     /**
-     * Gets the value of the {@code systemOutStreamConsumer} field.
-     * <p/>
-     * This option field if filled is used by the commandline tool to consume system ouput stream of the jarsigner
-     * command.
+     * <p>Gets the value of the {@code systemOutStreamConsumer} field.</p>
+     * <p>This option field if filled is used by the commandline tool to consume system ouput stream of the jarsigner
+     * command.</p>
      *
      * @return the value of the {@code systemOutStreamConsumer} field.
      */
     StreamConsumer getSystemOutStreamConsumer();
 
     /**
-     * Gets the value of the {@code systemErrorStreamConsumer} field.
-     * <p/>
-     * This option field if filled is used by the commandline tool to consume system error stream of the jarsigner
-     * command.
+     * <p>Gets the value of the {@code systemErrorStreamConsumer} field.</p>
+     * <p>This option field if filled is used by the commandline tool to consume system error stream of the jarsigner
+     * command.</p>
      *
      * @return the value of the {@code systemErrorStreamConsumer} field.
      */

src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolResult.java

@@ -25,7 +25,7 @@
 /**
  * Describes the result of a {@link JavaTool} invocation.
  *
- * @author Tony Chemit <chemit@codelutin.com>
+ * @author <a href="mailto:chemit@codelutin.com">Tony Chemit</a>
  * @since 0.5
  */
 public class JavaToolResult

src/main/java/org/apache/maven/shared/utils/cli/shell/BourneShell.java

@@ -111,7 +111,6 @@ protected String getExecutionPreamble()
 
     /**
      * <p>Unify quotes in a path for the Bourne Shell.</p>
-     * <p/>
      * <pre>
      * BourneShell.quoteOneItem(null)                       = null
      * BourneShell.quoteOneItem("")                         = ''

src/main/java/org/apache/maven/shared/utils/cli/shell/CmdShell.java

@@ -51,7 +51,6 @@ public CmdShell()
      * <p>
      * From cmd.exe /? output:
      * </p>
-     * <p/>
      * <pre>
      *      If /C or /K is specified, then the remainder of the command line after
      *      the switch is processed as a command line, where the following logic is
@@ -74,7 +73,6 @@ public CmdShell()
      *      remove the last quote character on the command line, preserving
      *      any text after the last quote character.
      * </pre>
-     * <p/>
      * <p>
      * Always quoting the entire command line, regardless of these conditions
      * appears to make Windows processes invoke successfully.