From 66e99e073b0d2b9a1924e51110eb6e9060d262a2 Mon Sep 17 00:00:00 2001 From: Maarten Mulders Date: Fri, 23 Apr 2021 17:37:00 +0200 Subject: [PATCH 1/7] Javadoc cleanup in preparation of release --- .../shared/utils/cli/javatool/JavaTool.java | 16 +++++----- .../ReflectionValueExtractor.java | 7 ++--- .../shared/utils/logging/MessageBuilder.java | 30 +++++++++++++++++++ .../shared/utils/logging/MessageUtils.java | 5 +++- 4 files changed, 43 insertions(+), 15 deletions(-) diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java index b4bc3a9a..9d5575c4 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java +++ b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java @@ -20,17 +20,15 @@ */ /** - * Describes a java tool, means a executable available in the jdk. - *

- * 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, ...}. - *

- * An abstract implementation of the {@link JavaTool} named {@link AbstractJavaTool} use the command line API to execute - * any user requests of this tool. + *

Describes a java tool, means a executable available in the jdk.

+ *

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, ...}.

+ *

An abstract implementation of the {@link JavaTool} named {@link AbstractJavaTool} use the command line API to + * execute any user requests of this tool.

* - * @author Tony Chemit + * @author Tony Chemit * @since 0.5 - * @param + * @param Tool-specific request type */ public interface JavaTool { diff --git a/src/main/java/org/apache/maven/shared/utils/introspection/ReflectionValueExtractor.java b/src/main/java/org/apache/maven/shared/utils/introspection/ReflectionValueExtractor.java index 963c9829..cf007cc7 100644 --- a/src/main/java/org/apache/maven/shared/utils/introspection/ReflectionValueExtractor.java +++ b/src/main/java/org/apache/maven/shared/utils/introspection/ReflectionValueExtractor.java @@ -36,7 +36,6 @@ /** *

Using simple dotted expressions to extract the values from an Object instance, * For example we might want to extract a value like: project.build.sourceDirectory

- *

*

The implementation supports indexed, nested and mapped properties similar to the JSP way.

* * @author Jason van Zyl @@ -146,14 +145,13 @@ private ReflectionValueExtractor() /** *

The implementation supports indexed, nested and mapped properties.

- *

*

    *
  • nested properties should be defined by a dot, i.e. "user.address.street"
    • *
  • indexed properties (java.util.List or array instance) should be contains (\\w+)\\[(\\d+)\\] * pattern, i.e. "user.addresses[1].street"
    • *
  • mapped properties should be contains (\\w+)\\((.+)\\) pattern, * i.e. "user.addresses(myAddress).street"
    • - *
      + *
    * * @param expression not null expression * @param root not null object @@ -170,14 +168,13 @@ public static Object evaluate( @Nonnull String expression, @Nullable Object root *

    * The implementation supports indexed, nested and mapped properties. *

    - *

    *

      *
    • nested properties should be defined by a dot, i.e. "user.address.street"
      • *
    • indexed properties (java.util.List or array instance) should be contains (\\w+)\\[(\\d+)\\] * pattern, i.e. "user.addresses[1].street"
      • *
    • mapped properties should be contains (\\w+)\\((.+)\\) pattern, i.e. * "user.addresses(myAddress).street"
      • - *
        + *
      * * @param expression not null expression * @param root not null object diff --git a/src/main/java/org/apache/maven/shared/utils/logging/MessageBuilder.java b/src/main/java/org/apache/maven/shared/utils/logging/MessageBuilder.java index 060e824e..649c0860 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/MessageBuilder.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/MessageBuilder.java @@ -29,36 +29,48 @@ public interface MessageBuilder /** * Append message content in success style. * By default, bold green + * @param message the message to append + * @return the current builder */ MessageBuilder success( Object message ); /** * Append message content in warning style. * By default, bold yellow + * @param message the message to append + * @return the current builder */ MessageBuilder warning( Object message ); /** * Append message content in failure style. * By default, bold red + * @param message the message to append + * @return the current builder */ MessageBuilder failure( Object message ); /** * Append message content in strong style. * By default, bold + * @param message the message to append + * @return the current builder */ MessageBuilder strong( Object message ); /** * Append message content in mojo style. * By default, green + * @param message the message to append + * @return the current builder */ MessageBuilder mojo( Object message ); /** * Append message content in project style. * By default, cyan + * @param message the message to append + * @return the current builder */ MessageBuilder project( Object message ); @@ -67,37 +79,55 @@ public interface MessageBuilder // /** * Append content to the message buffer. + * @param value the content to append + * @param offset the index of the first {@code char} to append + * @param len the number of {@code char}s to append + * @return the current builder */ MessageBuilder a( char[] value, int offset, int len ); /** * Append content to the message buffer. + * @param value the content to append + * @return the current builder */ MessageBuilder a( char[] value ); /** * Append content to the message buffer. + * @param value the content to append + * @param start the starting index of the subsequence to be appended + * @param end the end index of the subsequence to be appended + * @return the current builder */ MessageBuilder a( CharSequence value, int start, int end ); /** * Append content to the message buffer. + * @param value the content to append + * @return the current builder */ MessageBuilder a( CharSequence value ); /** * Append content to the message buffer. + * @param value the content to append + * @return the current builder */ MessageBuilder a( Object value ); /** * Append newline to the message buffer. + * @return the current builder */ MessageBuilder newline(); /** * Append formatted content to the buffer. * @see String#format(String, Object...) + * @param pattern a format string + * @param args arguments referenced by the format specifiers in the format string. + * @return the current builder */ MessageBuilder format( String pattern, Object... args ); } diff --git a/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java b/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java index 090b6a00..e98d2bb6 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java @@ -104,7 +104,7 @@ private static void doSystemUninstall() /** * Enables message color (if JAnsi is available). - * @param flag + * @param flag To enable JANSI */ public static void setColorEnabled( boolean flag ) { @@ -128,6 +128,7 @@ public static void setColorEnabled( boolean flag ) /** * Is message color enabled: requires JAnsi available (through Maven) and the color has not been disabled. + * @return whether colored messages are enabled */ public static boolean isColorEnabled() { @@ -145,6 +146,7 @@ public static MessageBuilder buffer() /** * Create a message buffer with defined String builder. + * @param builder Initial content of the message buffer * @return a new buffer */ public static MessageBuilder buffer( StringBuilder builder ) @@ -154,6 +156,7 @@ public static MessageBuilder buffer( StringBuilder builder ) /** * Create a message buffer with an internal buffer of defined size. + * @param size size of the buffer * @return a new buffer */ public static MessageBuilder buffer( int size ) From 69d1d741b9406705f0a0e641ff6e8ea5eaa19c61 Mon Sep 17 00:00:00 2001 From: Maarten Mulders Date: Fri, 23 Apr 2021 20:22:01 +0200 Subject: [PATCH 2/7] Correct casing for Jansi --- .../maven/shared/utils/logging/MessageUtils.java | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java b/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java index e98d2bb6..808728e5 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java @@ -46,7 +46,7 @@ public class MessageUtils boolean jansi = true; try { - // JAnsi is provided by Maven core since 3.5.0 + // Jansi is provided by Maven core since 3.5.0 Class.forName( "org.fusesource.jansi.Ansi" ); } catch ( ClassNotFoundException cnfe ) @@ -79,7 +79,7 @@ public static void systemUninstall() { doSystemUninstall(); - // hook can only set when JANSI is true + // hook can only set when Jansi is true if ( shutdownHook != null ) { try @@ -103,8 +103,8 @@ private static void doSystemUninstall() } /** - * Enables message color (if JAnsi is available). - * @param flag To enable JANSI + * Enables message color (if Jansi is available). + * @param flag to enable Jansi */ public static void setColorEnabled( boolean flag ) { @@ -127,7 +127,7 @@ public static void setColorEnabled( boolean flag ) } /** - * Is message color enabled: requires JAnsi available (through Maven) and the color has not been disabled. + * Is message color enabled: requires Jansi available (through Maven) and the color has not been disabled. * @return whether colored messages are enabled */ public static boolean isColorEnabled() From e643feb23bf2ebc8e02e90c99f092ea930a825e0 Mon Sep 17 00:00:00 2001 From: Maarten Mulders Date: Fri, 23 Apr 2021 20:23:58 +0200 Subject: [PATCH 3/7] Javadoc casing --- .../org/apache/maven/shared/utils/logging/MessageUtils.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java b/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java index 808728e5..f28058b7 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java @@ -146,7 +146,7 @@ public static MessageBuilder buffer() /** * Create a message buffer with defined String builder. - * @param builder Initial content of the message buffer + * @param builder initial content of the message buffer * @return a new buffer */ public static MessageBuilder buffer( StringBuilder builder ) From bbfbcb062e2657a0b7f0a13daf67d6440090e15d Mon Sep 17 00:00:00 2001 From: Maarten Mulders Date: Sat, 24 Apr 2021 19:46:06 +0200 Subject: [PATCH 4/7] Update Javadoc and rename method params --- .../utils/logging/AnsiMessageBuilder.java | 16 ++++++------- .../utils/logging/LoggerLevelRenderer.java | 24 +++++++++---------- .../utils/logging/PlainMessageBuilder.java | 16 ++++++------- 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuilder.java b/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuilder.java index 2d59bc9d..7f442397 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuilder.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuilder.java @@ -50,24 +50,24 @@ class AnsiMessageBuilder this.ansi = ansi; } - public String debug( String level ) + public String debug( String message ) { - return Style.DEBUG.apply( ansi ).a( level ).reset().toString(); + return Style.DEBUG.apply( ansi ).a( message ).reset().toString(); } - public String info( String level ) + public String info( String message ) { - return Style.INFO.apply( ansi ).a( level ).reset().toString(); + return Style.INFO.apply( ansi ).a( message ).reset().toString(); } - public String warning( String level ) + public String warning( String message ) { - return Style.WARNING.apply( ansi ).a( level ).reset().toString(); + return Style.WARNING.apply( ansi ).a( message ).reset().toString(); } - public String error( String level ) + public String error( String message ) { - return Style.ERROR.apply( ansi ).a( level ).reset().toString(); + return Style.ERROR.apply( ansi ).a( message ).reset().toString(); } public AnsiMessageBuilder success( Object message ) diff --git a/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java b/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java index 9dac0eb1..cbc31410 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java @@ -28,26 +28,26 @@ public interface LoggerLevelRenderer { /** - * Render DEBUG level. - * By default, bold cyan + * Render a message at DEBUG level. + * @param message the message to render. */ - String debug( String level ); + String debug( String message ); /** - * Render INFO level. - * By default, bold blue + * Render a message at INFO level. + * @param message the message to render. */ - String info( String level ); + String info( String message ); /** - * Render WARNING level. - * By default, bold yellow + * Render a message at WARNING level. + * @param message the message to render. */ - String warning( String level ); + String warning( String message ); /** - * Render ERROR level. - * By default, bold red + * Render a message at ERROR level. + * @param message the message to render. */ - String error( String level ); + String error( String message ); } diff --git a/src/main/java/org/apache/maven/shared/utils/logging/PlainMessageBuilder.java b/src/main/java/org/apache/maven/shared/utils/logging/PlainMessageBuilder.java index 6a7b56e1..5ff48844 100644 --- a/src/main/java/org/apache/maven/shared/utils/logging/PlainMessageBuilder.java +++ b/src/main/java/org/apache/maven/shared/utils/logging/PlainMessageBuilder.java @@ -42,24 +42,24 @@ class PlainMessageBuilder buffer = new StringBuilder( size ); } - public String debug( String level ) + public String debug( String message ) { - return a( level ).toString(); + return a( message ).toString(); } - public String info( String level ) + public String info( String message ) { - return a( level ).toString(); + return a( message ).toString(); } - public String warning( String level ) + public String warning( String message ) { - return a( level ).toString(); + return a( message ).toString(); } - public String error( String level ) + public String error( String message ) { - return a( level ).toString(); + return a( message ).toString(); } public PlainMessageBuilder success( Object message ) From 0e3b3658cfade35410fe518fbd9e695e0ef2ead0 Mon Sep 17 00:00:00 2001 From: Maarten Mulders Date: Sat, 24 Apr 2021 19:46:37 +0200 Subject: [PATCH 5/7] Remove duplicate ; --- .../apache/maven/shared/utils/xml/PrettyPrintXmlWriterTest.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/test/java/org/apache/maven/shared/utils/xml/PrettyPrintXmlWriterTest.java b/src/test/java/org/apache/maven/shared/utils/xml/PrettyPrintXmlWriterTest.java index d0611119..fdf81302 100644 --- a/src/test/java/org/apache/maven/shared/utils/xml/PrettyPrintXmlWriterTest.java +++ b/src/test/java/org/apache/maven/shared/utils/xml/PrettyPrintXmlWriterTest.java @@ -34,7 +34,7 @@ */ public class PrettyPrintXmlWriterTest { - private StringWriter w = new StringWriter();; + private StringWriter w = new StringWriter(); private PrettyPrintXMLWriter writer = new PrettyPrintXMLWriter( w ); @Test From 7b6d64846cfe1629b631eaa941280440e37b2d63 Mon Sep 17 00:00:00 2001 From: Maarten Mulders Date: Sat, 24 Apr 2021 19:59:35 +0200 Subject: [PATCH 6/7] Javadoc cleanup in preparation of release --- .../apache/maven/shared/utils/cli/Arg.java | 1 + .../maven/shared/utils/cli/Commandline.java | 9 +++-- .../shared/utils/cli/StreamConsumer.java | 9 +++-- .../utils/cli/javatool/AbstractJavaTool.java | 4 +-- .../cli/javatool/AbstractJavaToolRequest.java | 2 +- .../shared/utils/cli/javatool/JavaTool.java | 17 ++++------ .../utils/cli/javatool/JavaToolException.java | 11 +++--- .../utils/cli/javatool/JavaToolRequest.java | 16 ++++----- .../utils/cli/javatool/JavaToolResult.java | 2 +- .../shared/utils/cli/shell/BourneShell.java | 1 - .../shared/utils/cli/shell/CmdShell.java | 2 -- .../maven/shared/utils/cli/shell/Shell.java | 2 +- .../shared/utils/introspection/ClassMap.java | 13 +++---- .../maven/shared/utils/io/FileUtils.java | 20 +++++------ .../apache/maven/shared/utils/io/IOUtil.java | 34 +++++++++---------- .../maven/shared/utils/io/MatchPattern.java | 6 ++-- .../maven/shared/utils/io/MatchPatterns.java | 5 ++- .../maven/shared/utils/io/ScanConductor.java | 2 -- .../maven/shared/utils/io/SelectorUtils.java | 17 +++++----- .../utils/logging/LoggerLevelRenderer.java | 4 +++ .../shared/utils/xml/XmlReaderException.java | 29 +++++----------- .../utils/xml/XmlStreamReaderException.java | 10 +++--- 22 files changed, 95 insertions(+), 121 deletions(-) diff --git a/src/main/java/org/apache/maven/shared/utils/cli/Arg.java b/src/main/java/org/apache/maven/shared/utils/cli/Arg.java index 094cbba6..62f14ea6 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/Arg.java +++ b/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; diff --git a/src/main/java/org/apache/maven/shared/utils/cli/Commandline.java b/src/main/java/org/apache/maven/shared/utils/cli/Commandline.java index f430332a..e03e905c 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/Commandline.java +++ b/src/main/java/org/apache/maven/shared/utils/cli/Commandline.java @@ -37,15 +37,14 @@ import org.apache.maven.shared.utils.cli.shell.Shell; /** - *

      + *

      * Commandline objects help handling command lines specifying processes to * execute. *

      - *

      + *

      * 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. *

      - *

      * * <someelement>
      *   <acommandline executable="/executable/to/run">
      @@ -55,8 +54,7 @@ *   </acommandline>
      * </someelement>
      *       - *

      - *

      + *

      * The element someelement must provide a method * createAcommandline which returns an instance of this class. *

      @@ -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 { diff --git a/src/main/java/org/apache/maven/shared/utils/cli/StreamConsumer.java b/src/main/java/org/apache/maven/shared/utils/cli/StreamConsumer.java index 0cde961e..d64fba96 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/StreamConsumer.java +++ b/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 + *

      Works in concert with the StreamPumper class to * allow implementations to gain access to the lines being - * "Pumped". - *

      - * Please note that implementations of this interface can be expected to be - * called from arbitrary threads and must therefore be threadsafe. + * "Pumped".

      + *

      Please note that implementations of this interface can be expected to be + * called from arbitrary threads and must therefore be threadsafe.

      * * @author Florin Vancea * @author Paul Julius diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaTool.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaTool.java index 22826802..738f660d 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaTool.java +++ b/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 + * @author Tony Chemit * @since 0.5 - * @param + * @param Tool-specific request type */ public abstract class AbstractJavaTool extends AbstractLogEnabled diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaToolRequest.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaToolRequest.java index 6e18178a..597041b4 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/AbstractJavaToolRequest.java +++ b/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 + * @author Tony Chemit * @since 0.5 */ public class AbstractJavaToolRequest diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java index 9d5575c4..78b01701 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java +++ b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaTool.java @@ -34,10 +34,9 @@ public interface JavaTool { /** - * 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. - *

      - * For example: {@code jarsigner, keytool, javadoc, ...} + *

      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.

      + *

      For example: {@code jarsigner, keytool, javadoc, ...}

      * * @return the name of the java tool. */ @@ -53,13 +52,11 @@ public interface JavaTool void setToolchain( Object toolchain ); /** - * Execute the input request and then returns the result of the execution. - *

      - * If could not create the java tool invocation, a {@link JavaToolException} will be thrown. - *

      - * If execution fails, then the result will have a none-zero {@link JavaToolResult#getExitCode()} and his + *

      Execute the input request and then returns the result of the execution.

      + *

      If could not create the java tool invocation, a {@link JavaToolException} will be thrown.

      + *

      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.

      * * @param request the request to perform * @return the result of the tool execution diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java index fa10b33b..5a951ab6 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java +++ b/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. - *

      - * 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. + *

      Signals an error during the construction of the command line used to invoke java tool, e.g. illegal invocation + * arguments.

      + *

      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.

      * - * @author Tony Chemit + * @author Tony Chemit * * @see JavaToolResult#getExitCode() * @since 0.5 diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolRequest.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolRequest.java index 7227774c..6ad86b14 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolRequest.java +++ b/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 + * @author Tony Chemit * @since 0.5 */ public interface JavaToolRequest { /** - * Gets the value of the {@code systemOutStreamConsumer} field. - *

      - * This option field if filled is used by the commandline tool to consume system ouput stream of the jarsigner - * command. + *

      Gets the value of the {@code systemOutStreamConsumer} field.

      + *

      This option field if filled is used by the commandline tool to consume system ouput stream of the jarsigner + * command.

      * * @return the value of the {@code systemOutStreamConsumer} field. */ StreamConsumer getSystemOutStreamConsumer(); /** - * Gets the value of the {@code systemErrorStreamConsumer} field. - *

      - * This option field if filled is used by the commandline tool to consume system error stream of the jarsigner - * command. + *

      Gets the value of the {@code systemErrorStreamConsumer} field.

      + *

      This option field if filled is used by the commandline tool to consume system error stream of the jarsigner + * command.

      * * @return the value of the {@code systemErrorStreamConsumer} field. */ diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolResult.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolResult.java index f3a6a77e..deb830e8 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolResult.java +++ b/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 + * @author Tony Chemit * @since 0.5 */ public class JavaToolResult diff --git a/src/main/java/org/apache/maven/shared/utils/cli/shell/BourneShell.java b/src/main/java/org/apache/maven/shared/utils/cli/shell/BourneShell.java index e3af6651..f04864ea 100644 --- a/src/main/java/org/apache/maven/shared/utils/cli/shell/BourneShell.java +++ b/src/main/java/org/apache/maven/shared/utils/cli/shell/BourneShell.java @@ -111,7 +111,6 @@ protected String getExecutionPreamble() /** *

      Unify quotes in a path for the Bourne Shell.

      - *

      * 

            * BourneShell.quoteOneItem(null)                       = null
      * BourneShell.quoteOneItem("")                         = ''
diff --git a/src/main/java/org/apache/maven/shared/utils/cli/shell/CmdShell.java b/src/main/java/org/apache/maven/shared/utils/cli/shell/CmdShell.java
index 04aa6de1..06b7df73 100644
--- a/src/main/java/org/apache/maven/shared/utils/cli/shell/CmdShell.java
+++ b/src/main/java/org/apache/maven/shared/utils/cli/shell/CmdShell.java
@@ -51,7 +51,6 @@ public CmdShell()
      * 
      
      * From cmd.exe /? output:
      * 
      
-     * 
      
      * 
            *      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.
      * 
      
-     * 
      
      * 
      
      * Always quoting the entire command line, regardless of these conditions
      * appears to make Windows processes invoke successfully.
diff --git a/src/main/java/org/apache/maven/shared/utils/cli/shell/Shell.java b/src/main/java/org/apache/maven/shared/utils/cli/shell/Shell.java
index 02681086..47ec0dab 100644
--- a/src/main/java/org/apache/maven/shared/utils/cli/shell/Shell.java
+++ b/src/main/java/org/apache/maven/shared/utils/cli/shell/Shell.java
@@ -28,7 +28,7 @@
 
 /**
  * Class that abstracts the Shell functionality,
- * with subclasses for shells that behave particularly, like
      
+ * with subclasses for shells that behave particularly, like
  * 
  * 
        
  * 
      • command.com
        • 
diff --git a/src/main/java/org/apache/maven/shared/utils/introspection/ClassMap.java b/src/main/java/org/apache/maven/shared/utils/introspection/ClassMap.java
index 19b17322..357eab45 100644
--- a/src/main/java/org/apache/maven/shared/utils/introspection/ClassMap.java
+++ b/src/main/java/org/apache/maven/shared/utils/introspection/ClassMap.java
@@ -79,16 +79,13 @@ Class getCachedClass()
     }
 
     /**
-     * Find a Method using the methodKey
-     * provided.
-     * 
        
-     * Look in the methodMap for an entry.  If found,
+     * 
        Find a Method using the methodKey provided.
        
+     * 
        Look in the methodMap for an entry. If found,
      * it'll either be a CACHE_MISS, in which case we
      * simply give up, or it'll be a Method, in which
-     * case, we return it.
-     * 
        
-     * If nothing is found, then we must actually go
-     * and introspect the method from the MethodMap.
+     * case, we return it.
        
+     * 
        If nothing is found, then we must actually go
+     * and introspect the method from the MethodMap.
        
      * @param name Method name.
      * @param params Method parameters.
      * @return The found method.
diff --git a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
index 4612b37f..9fc64ca9 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
@@ -47,6 +47,7 @@
 import java.nio.charset.CoderResult;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.attribute.FileAttribute;
 import java.security.SecureRandom;
 import java.text.DecimalFormat;
 import java.util.ArrayList;
@@ -68,21 +69,21 @@
  * 
      • html -- retrievable through {@link #getExtension}
        • 
  * 
      
  * 
      
- * 
      
  * 
      File-related methods
      
  * 
- * There are methods to create a {@link #toFile File from a URL}, copy a
+ * 
      There are methods to create a {@link #toFile File from a URL}, copy a
  * {@link #copyFile File to another File},
  * copy a {@link #copyURLToFile URL's contents to a File},
  * as well as methods to {@link #deleteDirectory(File) delete} and {@link #cleanDirectory(File)
  * clean} a directory.
- * 
      
- * Common {@link java.io.File} manipulation routines.
- * 
      
+ * 
      
+ * 
      Common {@link java.io.File} manipulation routines.
      
+ * 
      
  * Taken from the commons-utils repo.
  * Also code from Alexandria's FileUtils.
  * And from Avalon Excalibur's IO.
  * And from Ant.
+ * 
      
  *
  * @author Kevin A. Burton
  * @author Scott Sanders
@@ -1804,8 +1805,7 @@ public static void rename( @Nonnull File from, @Nonnull File to )
     }
 
     /**
-     * Create a temporary file in a given directory.
-     * 
      
+     * 
      Create a temporary file in a given directory.
      
      * 
      The file denoted by the returned abstract pathname did not
      * exist before this method was invoked, any subsequent invocation
      * of this method will yield a different file name.
      
@@ -1895,7 +1895,7 @@ public abstract static class FilterWrapper
      * @param encoding the file output encoding (only if wrappers is not empty)
      * @param wrappers array of {@link FilterWrapper}
      * @param overwrite if true and wrappers is null or empty, the file will be copied even if
-     *         to.lastModified() < from.lastModified()
+     *         to.lastModified() < from.lastModified()
      * @throws IOException if an IO error occurs during copying or filtering
      */
     public static void copyFile( @Nonnull File from, @Nonnull File to, @Nullable String encoding,
@@ -2144,8 +2144,8 @@ public static boolean isSymbolicLinkForSure( @Nonnull final File file )
      * @param target the target
      * @return the linked file
      * @throws IOException in case of an error
-     * @see {@code java.nio.file.Files.createSymbolicLink(Path)} which creates a new
-     *         symbolic link but does not replace existing symbolic links
+     * @see Files#createSymbolicLink(Path, Path, FileAttribute[]) which creates a new symbolic link but does
+     * not replace existing symbolic links
      */
     @Nonnull public static File createSymbolicLink( @Nonnull File symlink,  @Nonnull File target )
             throws IOException
diff --git a/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java b/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java
index 11f1bdd4..534a4a02 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java
@@ -37,12 +37,12 @@
 import java.nio.channels.Channel;
 
 /**
- * General IO Stream manipulation.
+ * 
      General IO Stream manipulation.
      
  * 
      
  * This class provides static utility methods for input/output operations, particularly buffered
  * copying between sources (InputStream, Reader, String and
  * byte[]) and destinations (OutputStream, Writer,
- * String and byte[]).
+ * String and byte[]).
      
  * 
  * 
      Unless otherwise noted, these copy methods do not flush or close the
  * streams. Often, doing so would require making non-portable assumptions about the streams' origin
@@ -837,7 +837,7 @@ public static boolean contentEquals( @Nonnull final InputStream input1, @Nonnull
     // ----------------------------------------------------------------------
 
     /**
-     * Closes a {@code Channel} suppressing any {@code IOException}.
+     * 
      Closes a {@code Channel} suppressing any {@code IOException}.
      
      * 
      
      * Note: The use case justifying this method is a shortcoming of the Java language up to but not including
      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
@@ -847,7 +847,8 @@ public static boolean contentEquals( @Nonnull final InputStream input1, @Nonnull
      * {@code finally} block incorrectly by using this method.
      * 
      
      * 
      
-     * Example:
      
+     * Example:
+     * 
      
      * 
            * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
      * Closeable resource1 = null;
@@ -921,7 +922,6 @@ public static boolean contentEquals( @Nonnull final InputStream input1, @Nonnull
      *     // }
      * }
      * 
      
-     * 
      
      *
      * @param channel The channel to close or {@code null}.
      * @deprecated use try-with-resources
@@ -943,7 +943,7 @@ public static void close( @Nullable Channel channel )
     }
 
     /**
-     * Closes an {@code InputStream} suppressing any {@code IOException}.
+     * 
      Closes an {@code InputStream} suppressing any {@code IOException}.
      
      * 
      
      * Note: The use case justifying this method is a shortcoming of the Java language up to but not including
      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
@@ -953,7 +953,8 @@ public static void close( @Nullable Channel channel )
      * {@code finally} block incorrectly by using this method.
      * 
      
      * 
      
-     * Example:
      
+     * Example:
+     * 
      
      * 
            * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
      * Closeable resource1 = null;
@@ -1027,7 +1028,6 @@ public static void close( @Nullable Channel channel )
      *     // }
      * }
      * 
      
-     * 
      
      *
      * @param inputStream The stream to close or {@code null}.
      * @deprecated use try-with-resources
@@ -1049,7 +1049,7 @@ public static void close( @Nullable InputStream inputStream )
     }
 
     /**
-     * Closes an {@code OutputStream} suppressing any {@code IOException}.
+     * 
      Closes an {@code OutputStream} suppressing any {@code IOException}.
      
      * 
      
      * Note: The use case justifying this method is a shortcoming of the Java language up to but not including
      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
@@ -1059,7 +1059,8 @@ public static void close( @Nullable InputStream inputStream )
      * {@code finally} block incorrectly by using this method.
      * 
      
      * 
      
-     * Example:
      
+     * Example:
+     * 
      
      * 
            * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
      * Closeable resource1 = null;
@@ -1133,7 +1134,6 @@ public static void close( @Nullable InputStream inputStream )
      *     // }
      * }
      * 
      
-     * 
      
      *
      * @param outputStream The stream to close or {@code null}.
      * @deprecated use try-with-resources
@@ -1155,7 +1155,7 @@ public static void close( @Nullable OutputStream outputStream )
     }
 
     /**
-     * Closes a {@code Reader} suppressing any {@code IOException}.
+     * 
      Closes a {@code Reader} suppressing any {@code IOException}.
      
      * 
      
      * Note: The use case justifying this method is a shortcoming of the Java language up to but not including
      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
@@ -1165,7 +1165,8 @@ public static void close( @Nullable OutputStream outputStream )
      * {@code finally} block incorrectly by using this method.
      * 
      
      * 
      
-     * Example:
      
+     * Example:
+     * 
      
      * 
            * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
      * Closeable resource1 = null;
@@ -1239,7 +1240,6 @@ public static void close( @Nullable OutputStream outputStream )
      *     // }
      * }
      * 
      
-     * 
      
      *
      * @param reader The reader to close or {@code null}.
      * @deprecated use try-with-resources
@@ -1261,7 +1261,7 @@ public static void close( @Nullable Reader reader )
     }
 
     /**
-     * Closes a {@code Writer} suppressing any {@code IOException}.
+     * 
      Closes a {@code Writer} suppressing any {@code IOException}.
      
      * 
      
      * Note: The use case justifying this method is a shortcoming of the Java language up to but not including
      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
@@ -1271,7 +1271,8 @@ public static void close( @Nullable Reader reader )
      * {@code finally} block incorrectly by using this method.
      * 
      
      * 
      
-     * Example:
      
+     * Example:
+     * 
      
      * 
            * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
      * Closeable resource1 = null;
@@ -1345,7 +1346,6 @@ public static void close( @Nullable Reader reader )
      *     // }
      * }
      * 
      
-     * 
      
      *
      * @param writer The writer to close or {@code null}.
      * @deprecated use try-with-resources
diff --git a/src/main/java/org/apache/maven/shared/utils/io/MatchPattern.java b/src/main/java/org/apache/maven/shared/utils/io/MatchPattern.java
index 8abff427..bdce10d7 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/MatchPattern.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/MatchPattern.java
@@ -28,9 +28,9 @@
 import javax.annotation.Nonnull;
 
 /**
- * Describes a match target for SelectorUtils.
- * 
      
- * Significantly more efficient than using strings, since re-evaluation and re-tokenizing is avoided.
+ * 
      Describes a match target for SelectorUtils.
      
+ * 
      
+ * Significantly more efficient than using strings, since re-evaluation and re-tokenizing is avoided.
      
  *
  * @author Kristian Rosenvold
  * @deprecated use {@code java.nio.filejava.nio.file.DirectoryStream.Filter} and related classes
diff --git a/src/main/java/org/apache/maven/shared/utils/io/MatchPatterns.java b/src/main/java/org/apache/maven/shared/utils/io/MatchPatterns.java
index 693acb1c..638586f2 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/MatchPatterns.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/MatchPatterns.java
@@ -40,9 +40,8 @@ private MatchPatterns( @Nonnull MatchPattern... patterns )
     }
 
     /**
-     * Checks these MatchPatterns against a specified string.
-     * 
      
-     * Uses far less string tokenization than any of the alternatives.
+     * 
      Checks these MatchPatterns against a specified string.
      
+     * 
      Uses far less string tokenization than any of the alternatives.
      
      *
      * @param name            The name to look for
      * @param isCaseSensitive If the comparison is case sensitive
diff --git a/src/main/java/org/apache/maven/shared/utils/io/ScanConductor.java b/src/main/java/org/apache/maven/shared/utils/io/ScanConductor.java
index 08d7a1cd..0a0d82d7 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/ScanConductor.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/ScanConductor.java
@@ -23,12 +23,10 @@
 
 /**
  * 
      Visitor pattern for the DirectoryScanner. A ScanConductor controls the scanning process.
      
- * 
      
  * 
      Create an instance and pass it to
  * {@link org.apache.maven.shared.utils.io.DirectoryScanner#setScanConductor(ScanConductor)}.
  * You will get notified about every visited directory and file. You can use the {@link ScanAction}
  * to control what should happen next.
      
- * 
      
  * 
      A ScanConductor might also store own information but users must make sure that the state gets
  * cleaned between two scan() invocations.
      
  *
diff --git a/src/main/java/org/apache/maven/shared/utils/io/SelectorUtils.java b/src/main/java/org/apache/maven/shared/utils/io/SelectorUtils.java
index b716e7c8..56a43992 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/SelectorUtils.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/SelectorUtils.java
@@ -73,12 +73,12 @@ private SelectorUtils()
     }
 
     /**
-     * Tests whether or not a given path matches the start of a given
-     * pattern up to the first "**".
-     * 
      
+     * 
      Tests whether or not a given path matches the start of a given
+     * pattern up to the first "**".
      
+     * 
      
      * This is not a general purpose test and should only be used if you
      * can live with false positives. For example, pattern=**\a
-     * and str=b will yield true.
+     * and str=b will yield true.
      
      *
      * @param pattern The pattern to match against. Must not be
      *                null.
@@ -93,12 +93,11 @@ public static boolean matchPatternStart( String pattern, String str )
     }
 
     /**
-     * Tests whether or not a given path matches the start of a given
-     * pattern up to the first "**".
-     * 
      
-     * This is not a general purpose test and should only be used if you
+     * 
      Tests whether or not a given path matches the start of a given
+     * pattern up to the first "**".
      
+     * 
      This is not a general purpose test and should only be used if you
      * can live with false positives. For example, pattern=**\a
-     * and str=b will yield true.
+     * and str=b will yield true.
      
      *
      * @param pattern         The pattern to match against. Must not be
      *                        null.
diff --git a/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java b/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java
index cbc31410..6caa797b 100644
--- a/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java
+++ b/src/main/java/org/apache/maven/shared/utils/logging/LoggerLevelRenderer.java
@@ -30,24 +30,28 @@ public interface LoggerLevelRenderer
     /**
      * Render a message at DEBUG level.
      * @param message the message to render.
+     * @return the formatted message.
      */
     String debug( String message );
     
     /**
      * Render a message at INFO level.
      * @param message the message to render.
+     * @return the formatted message.
      */
     String info( String message );
     
     /**
      * Render a message at WARNING level.
      * @param message the message to render.
+     * @return the formatted message.
      */
     String warning( String message );
     
     /**
      * Render a message at ERROR level.
      * @param message the message to render.
+     * @return the formatted message.
      */
     String error( String message );
 }
diff --git a/src/main/java/org/apache/maven/shared/utils/xml/XmlReaderException.java b/src/main/java/org/apache/maven/shared/utils/xml/XmlReaderException.java
index f1bc0c6f..5ee48a01 100644
--- a/src/main/java/org/apache/maven/shared/utils/xml/XmlReaderException.java
+++ b/src/main/java/org/apache/maven/shared/utils/xml/XmlReaderException.java
@@ -23,12 +23,11 @@
 import java.io.InputStream;
 
 /**
- * The XmlReaderException is thrown by the XmlReader constructors if the charset encoding can not be determined
- * according to the XML 1.0 specification and RFC 3023.
- * 
      
- * The exception returns the unconsumed InputStream to allow the application to do an alternate processing with the
- * stream. Note that the original InputStream given to the XmlReader cannot be used as that one has been already read.
- * 
      
+ * 
      The XmlReaderException is thrown by the XmlReader constructors if the charset encoding can not be determined
+ * according to the XML 1.0 specification and RFC 3023.
      
+ * 
      The exception returns the unconsumed InputStream to allow the application to do an alternate processing with the
+ * stream. Note that the original InputStream given to the XmlReader cannot be used as that one has been already
+ * read.
      
  *
  * @author Alejandro Abdelnur
  * @version revision 1.1 taken on 26/06/2007 from Rome (see https://rome.dev.java.net/source/browse/rome/src/java/com/sun/syndication/io/XmlReaderException.java)
@@ -54,10 +53,8 @@ class XmlReaderException
     private final InputStream is;
 
     /**
-     * Creates an exception instance if the charset encoding could not be determined.
-     * 
      
-     * Instances of this exception are thrown by the XmlReader.
-     * 
      
+     * 
      Creates an exception instance if the charset encoding could not be determined.
      
+     * 
      Instances of this exception are thrown by the XmlReader.
      
      *
      * @param msg         message describing the reason for the exception.
      * @param bomEnc      BOM encoding.
@@ -71,10 +68,8 @@ class XmlReaderException
     }
 
     /**
-     * Creates an exception instance if the charset encoding could not be determined.
-     * 
      
-     * Instances of this exception are thrown by the XmlReader.
-     * 
      
+     * 
      Creates an exception instance if the charset encoding could not be determined.
      
+     * 
      Instances of this exception are thrown by the XmlReader.
      
      *
      * @param msg         message describing the reason for the exception.
      * @param ctMime      MIME type in the content-type.
@@ -98,7 +93,6 @@ class XmlReaderException
 
     /**
      * Returns the BOM encoding found in the InputStream.
-     * 
      
      *
      * @return the BOM encoding, null if none.
      */
@@ -109,7 +103,6 @@ public String getBomEncoding()
 
     /**
      * Returns the encoding guess based on the first bytes of the InputStream.
-     * 
      
      *
      * @return the encoding guess, null if it couldn't be guessed.
      */
@@ -120,7 +113,6 @@ public String getXmlGuessEncoding()
 
     /**
      * Returns the encoding found in the XML prolog of the InputStream.
-     * 
      
      *
      * @return the encoding of the XML prolog, null if none.
      */
@@ -131,7 +123,6 @@ public String getXmlEncoding()
 
     /**
      * Returns the MIME type in the content-type used to attempt determining the encoding.
-     * 
      
      *
      * @return the MIME type in the content-type, null if there was not content-type or the encoding detection did not
      *         involve HTTP.
@@ -143,7 +134,6 @@ public String getContentTypeMime()
 
     /**
      * Returns the encoding in the content-type used to attempt determining the encoding.
-     * 
      
      *
      * @return the encoding in the content-type, null if there was not content-type, no encoding in it or the encoding
      *         detection did not involve HTTP.
@@ -156,7 +146,6 @@ public String getContentTypeEncoding()
     /**
      * Returns the unconsumed InputStream to allow the application to do an alternate encoding detection on the
      * InputStream.
-     * 
      
      *
      * @return the unconsumed InputStream.
      */
diff --git a/src/main/java/org/apache/maven/shared/utils/xml/XmlStreamReaderException.java b/src/main/java/org/apache/maven/shared/utils/xml/XmlStreamReaderException.java
index eeabae53..992b833c 100644
--- a/src/main/java/org/apache/maven/shared/utils/xml/XmlStreamReaderException.java
+++ b/src/main/java/org/apache/maven/shared/utils/xml/XmlStreamReaderException.java
@@ -22,13 +22,11 @@
 import java.io.InputStream;
 
 /**
- * The XmlStreamReaderException is thrown by the XmlStreamReader constructors if the charset encoding can not be
- * determined according to the XML 1.0 specification and RFC 3023.
- * 
      
- * The exception returns the unconsumed InputStream to allow the application to do an alternate processing with the
+ * 
      The XmlStreamReaderException is thrown by the XmlStreamReader constructors if the charset encoding can not be
+ * determined according to the XML 1.0 specification and RFC 3023.
      
+ * 
      The exception returns the unconsumed InputStream to allow the application to do an alternate processing with the
  * stream. Note that the original InputStream given to the XmlStreamReader cannot be used as that one has been already
- * read.
- * 
      
+ * read.
      
  *
  * @author Alejandro Abdelnur
  * @version revision 1.1 taken on 26/06/2007 from Rome (see

From e061ed255bcd55cb88e9f22e6c728d6db4ca48d5 Mon Sep 17 00:00:00 2001
From: Maarten Mulders 
Date: Sat, 24 Apr 2021 22:10:36 +0200
Subject: [PATCH 7/7] Javadoc cleanup in preparation of release

---
 .../org/apache/maven/shared/utils/Os.java     |  4 +-
 .../apache/maven/shared/utils/PathTool.java   | 14 ++--
 .../maven/shared/utils/StringUtils.java       | 34 ++++------
 .../utils/cli/javatool/JavaToolException.java |  4 +-
 .../shared/utils/io/DirectoryScanner.java     | 68 +++++++++++--------
 .../maven/shared/utils/io/FileUtils.java      | 43 ++++++------
 6 files changed, 85 insertions(+), 82 deletions(-)

diff --git a/src/main/java/org/apache/maven/shared/utils/Os.java b/src/main/java/org/apache/maven/shared/utils/Os.java
index c4c5f33b..a2c3d529 100644
--- a/src/main/java/org/apache/maven/shared/utils/Os.java
+++ b/src/main/java/org/apache/maven/shared/utils/Os.java
@@ -26,12 +26,10 @@
 
 /**
  * 
      Condition that tests the OS type.
      
- * 
      
  * 
      This class got copied over from Apache ANT.
  * Even the version from plexus-utils was
- * only an ANT fork!
      
+ * only an ANT fork!
  * The last time it got copied was on 2011-08-12
      
- * 
      
  * 
      When merging changes please take care of the special
  * OS_FAMILY handling in this version of Os.java!
      
  *
diff --git a/src/main/java/org/apache/maven/shared/utils/PathTool.java b/src/main/java/org/apache/maven/shared/utils/PathTool.java
index 28bc3083..2a0b0fe5 100644
--- a/src/main/java/org/apache/maven/shared/utils/PathTool.java
+++ b/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.
- * 
      
+ * 
      Path tool contains static methods to assist in determining path-related
+ * information such as relative paths.
      
+ * 
      
  * 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.
+ * 
      
  */
 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).
-     * 
      
+     * 
      
      * This method is thread-safe.
-     * 
      
+     * 
      
      * 
            * 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.
-     * 
      
+     * 
      This method can calculate the relative path between two paths on a file system.
      
      * 
            * PathTool.getRelativeFilePath( null, null )                                   = ""
      * PathTool.getRelativeFilePath( null, "/usr/local/java/bin" )                  = ""
diff --git a/src/main/java/org/apache/maven/shared/utils/StringUtils.java b/src/main/java/org/apache/maven/shared/utils/StringUtils.java
index b70cdae8..de4a1e88 100644
--- a/src/main/java/org/apache/maven/shared/utils/StringUtils.java
+++ b/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 )
 
     /**
      * 
      Checks if a String is non null and is
-     * not empty (length > 0).
      
+     * not empty (length > 0).
      
      *
      * @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
     //--------------------------------------------------------------------------
 
     /**
-     * 
      Center a String in a larger String of size n.
      
+     * 
      Center a String in a larger String of size n.
      
      *
      * 
      Uses spaces as the value to buffer the String with.
      * Equivalent to center(str, size, " ").
      
@@ -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 repeat < 0
+     * @throws NegativeArraySizeException if repeat < 0
      * @throws NullPointerException       if str is null
      */
     @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..."
-     * 
      
-     * Specifically:
-     * 
      
-     * If str is less than max characters long, return it.
+     * 
      Turn "Now is the time for all good men" into "Now is the time for..."
      
+     * 
      Specifically:
      
+     * 
      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.
      
      * 
      * @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..."
-     * 
      
+     * 
      
      * 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.
+     * 
      
      * 
      * @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.)
-     * 
      
-     * E.g. strdiff("i am a machine", "i am a robot") -> "robot"
+     * 
      
+     * E.g. strdiff("i am a machine", "i am a robot") → "robot"
+     * 
      
      *
      * @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.
      * 
      
-     * E.g. strdiff("i am a machine", "i am a robot") -> 7
+     * E.g. strdiff("i am a machine", "i am a robot") → 7
      * 
      
      *
      * @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 not trim spaces!
-     * 
      
      *
      * @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.
-     * 
      
-     * 'ThisIsIt' will become 'this-is-it'.
+     * 
      Take the input string and un-camel-case it.
      
+     * 
      'ThisIsIt' will become 'this-is-it'.
      
      *
      * @param view the view
      * @return deHumped String
@@ -2519,7 +2516,6 @@ public static boolean contains( @Nullable String str, @Nullable String searchStr
 
     /**
      * 
      Checks if String ends with a search String, handling null.
      
-     * 
      
      * 
      A null String will return false.
      
      *
      * 
      diff --git a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java
index 5a951ab6..fb9d6946 100644
--- a/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java
+++ b/src/main/java/org/apache/maven/shared/utils/cli/javatool/JavaToolException.java
@@ -22,8 +22,8 @@
 /**
  * 
      Signals an error during the construction of the command line used to invoke java tool, e.g. illegal invocation
  * arguments.
      
- * 
      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.
      
+ * 
      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.
      
  *
  * @author Tony Chemit
  *
diff --git a/src/main/java/org/apache/maven/shared/utils/io/DirectoryScanner.java b/src/main/java/org/apache/maven/shared/utils/io/DirectoryScanner.java
index 5d03525e..bd8bd7d9 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/DirectoryScanner.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/DirectoryScanner.java
@@ -32,56 +32,62 @@
 import javax.annotation.Nullable;
 
 /**
- * Class for scanning a directory for files/directories which match certain criteria.
- * 
      
+ * 
      Class for scanning a directory for files/directories which match certain criteria.
      
+ * 
      
  * These criteria consist of selectors and patterns which have been specified. With the selectors you can select which
  * files you want to have included. Files which are not selected are excluded. With patterns you can include or exclude
  * files based on their filename.
- * 
      
+ * 
      
+ * 
      
  * The idea is simple. A given directory is recursively scanned for all files and directories. Each file/directory is
  * matched against a set of selectors, including special support for matching against filenames with include and and
  * exclude patterns. Only files/directories which match at least one pattern of the include pattern list or other file
  * selector, and don't match any pattern of the exclude pattern list or fail to match against a required selector will
  * be placed in the list of files/directories found.
- * 
      
+ * 
      
+ * 
      
  * When no list of include patterns is supplied, "**" will be used, which means that everything will be matched. When no
  * list of exclude patterns is supplied, an empty list is used, such that nothing will be excluded. When no selectors
  * are supplied, none are applied.
- * 
      
+ * 
      
+ * 
      
  * The filename pattern matching is done as follows: The name to be matched is split up in path segments. A path segment
  * is the name of a directory or file, which is bounded by File.separator ('/' under UNIX, '\' under
  * Windows). For example, "abc/def/ghi/xyz.java" is split up in the segments "abc", "def","ghi" and "xyz.java". The same
  * is done for the pattern against which should be matched.
- * 
      
+ * 
      
+ * 
      
  * The segments of the name and the pattern are then matched against each other. When '**' is used for a path segment in
  * the pattern, it matches zero or more path segments of the name.
- * 
      
+ * 
      
+ * 
      
  * There is a special case regarding the use of File.separators at the beginning of the pattern and the
  * string to match:
      
  * When a pattern starts with a File.separator, the string to match must also start with a
  * File.separator. When a pattern does not start with a File.separator, the string to match
  * may not start with a File.separator. When one of these rules is not obeyed, the string will not match.
- * 
      
+ * 
      
+ * 
      
  * When a name path segment is matched against a pattern path segment, the following special characters can be used:
      
  * '*' matches zero or more characters
      
  * '?' matches one character.
- * 
      
+ * 
      
+ * 
      
  * Examples:
- * 
      
- * "**\*.class" matches all .class files/dirs in a directory tree.
- * 
      
- * "test\a??.java" matches all files/dirs which start with an 'a', then two more characters and then ".java", in a
- * directory called test.
- * 
      
- * "**" matches everything in a directory tree.
- * 
      
- * "**\test\**\XYZ*" matches all files/dirs which start with "XYZ" and where there is a parent directory called test
- * (e.g. "abc\test\def\ghi\XYZ123").
- * 
      
+ * 
        
+ * 
      • "**\*.class" matches all .class files/dirs in a directory tree.
        • 
+ * 
      • "test\a??.java" matches all files/dirs which start with an 'a', then two more characters and then ".java", in a
+ * directory called test.
        • 
+ * 
      • "**" matches everything in a directory tree.
        • 
+ * 
      • "**\test\**\XYZ*" matches all files/dirs which start with "XYZ" and where there is a parent directory called test
+ * (e.g. "abc\test\def\ghi\XYZ123").
        • 
+ * 
      
+ * 
      
  * Case sensitivity may be turned off if necessary. By default, it is turned on.
- * 
      
+ * 
      
+ * 
      
  * Example of usage:
- * 
      
+ * 
      
  * 
        * String[] includes = { "**\\*.class" };
  * String[] excludes = { "modules\\*\\**" };
@@ -98,11 +104,13 @@
  *     System.out.println( files[i] );
  * }
  * 
      
- * 
      
+ * 
      
  * This will scan a directory called test for .class files, but excludes all files in all proper subdirectories of a
  * directory called "modules"
- * 
      
+ * 
      
+ * 
      
  * This class must not be used from multiple Threads concurrently!
+ * 
      
  *
  * @author Arnout J. Kuiper ajkuiper@wxs.nl
  * @author Magesh Umasankar
@@ -295,8 +303,9 @@ public void setFollowSymlinks( final boolean followSymlinks )
     /**
      * Sets the list of include patterns to use. All '/' and '\' characters are replaced by
      * File.separatorChar, so the separator used need not match File.separatorChar.
-     * 
      
+     * 
      
      * When a pattern ends with a '/' or '\', "**" is appended.
+     * 
      
      *
      * @param includes A list of include patterns. May be null, indicating that all files should be
      *                 included. If a non-null list is given, all elements must be non-null.
@@ -326,8 +335,9 @@ public void setIncludes( final String... includes )
     /**
      * Sets the list of exclude patterns to use. All '/' and '\' characters are replaced by
      * File.separatorChar, so the separator used need not match File.separatorChar.
-     * 
      
+     * 
      
      * When a pattern ends with a '/' or '\', "**" is appended.
+     * 
      
      *
      * @param excludes A list of exclude patterns. May be null, indicating that no files should be
      *                 excluded. If a non-null list is given, all elements must be non-null.
@@ -431,13 +441,15 @@ public void scan()
      * a previously captured list of files.
      * This method will not look for a changed in content but sole in the
      * list of files given.
-     * 
      
+     * 
      
      * The method will compare the given array of file Strings with the result
      * of the last directory scan. It will execute a {@link #scan()} if no
      * result of a previous scan could be found.
-     * 
      
+     * 
      
+     * 
      
      * The result of the diff can be queried by the methods
      * {@link DirectoryScanResult#getFilesAdded()} and {@link DirectoryScanResult#getFilesRemoved()}
+     * 
      
      *
      * @param oldFiles the list of previously captured files names.
      * @return the result of the directory scan.
diff --git a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
index 9fc64ca9..4d80e180 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
@@ -47,7 +47,6 @@
 import java.nio.charset.CoderResult;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.nio.file.attribute.FileAttribute;
 import java.security.SecureRandom;
 import java.text.DecimalFormat;
 import java.util.ArrayList;
@@ -62,13 +61,13 @@
  *
  * 
      Path-related methods
      
  * 
- * 
      Methods exist to retrieve the components of a typical file path. For example
+ * Methods exist to retrieve the components of a typical file path. For example
  * /www/hosted/mysite/index.html, can be broken into:
  * 
        
  * 
      • /www/hosted/mysite/index -- retrievable through {@link #removeExtension}
        • 
  * 
      • html -- retrievable through {@link #getExtension}
        • 
  * 
      
- * 
      
+ *
  * 
      File-related methods
      
  * 
  * 
      There are methods to create a {@link #toFile File from a URL}, copy a
@@ -483,8 +482,8 @@ public static void fileDelete( @Nonnull String fileName )
 
     /**
      * Given a directory and an array of extensions return an array of compliant files.
-     * 
      
-     * The given extensions should be like "java" and not like ".java".
+     *
+     * 
      The given extensions should be like "java" and not like ".java".
      
      *
      * @param directory  the path of the directory
      * @param extensions an array of expected extensions
@@ -689,9 +688,9 @@ public static boolean contentEquals( @Nonnull final File file1, @Nonnull final F
     /**
      * Remove extension from a path. E.g.
      * 
      -     * foo.txt    --> foo
-     * a\b\c.jpg --> a\b\c
-     * a\b\c     --> a\b\c
+     * foo.txt    → foo
+     * a\b\c.jpg  → a\b\c
+     * a\b\c      → a\b\c
      * 
      
      *
      * @param filename the path of the file
@@ -716,9 +715,9 @@ public static boolean contentEquals( @Nonnull final File file1, @Nonnull final F
      * Get extension from a path. E.g.
      *
      * 
      -     * foo.txt    --> "txt"
-     * a\b\c.jpg --> "jpg"
-     * a\b\c     --> ""
+     * foo.txt    → "txt"
+     * a\b\c.jpg  → "jpg"
+     * a\b\c      → ""
      * 
      
      *
      * @param filename the path of the file
@@ -963,13 +962,13 @@ private static void copyStreamToFile( @Nonnull @WillClose final InputStream sour
      * root.
      * Eg:
      * 
      -     * /foo//               -->     /foo/
-     * /foo/./              -->     /foo/
-     * /foo/../bar          -->     /bar
-     * /foo/../bar/         -->     /bar/
-     * /foo/../bar/../baz   -->     /baz
-     * //foo//./bar         -->     /foo/bar
-     * /../                 -->     null
+     * /foo//               →     /foo/
+     * /foo/./              →     /foo/
+     * /foo/../bar          →     /bar
+     * /foo/../bar/         →     /bar/
+     * /foo/../bar/../baz   →     /baz
+     * //foo//./bar         →     /foo/bar
+     * /../                 →     null
      * 
      
      *
      * @param path the path to normalize
@@ -1667,8 +1666,7 @@ else if ( !sourceDirectory.isDirectory() )
 
     /**
      * Copies an entire directory structure.
-     * 
      
-     * Note:
+     * 
      Note:
      
      * 
        
      * 
      • It will include empty directories.
      * 
      • The sourceDirectory must exist.
@@ -1767,7 +1765,6 @@ else if ( file.isDirectory() )
 
     /**
      * Renames a file, even if that involves crossing file system boundaries.
-     * 
        
      * 
        This will remove to (if it exists), ensure that
      * to's parent directory exists and move
      * from, which involves deleting from as
@@ -1859,7 +1856,7 @@ private static int positiveRandom( Random rand )
     }
 
     /**
-     * If wrappers is null or empty, the file will be copied only if to.lastModified() < from.lastModified()
+     * If wrappers is null or empty, the file will be copied only if to.lastModified() < from.lastModified()
      *
      * @param from     the file to copy
      * @param to       the destination file
@@ -1887,7 +1884,7 @@ public abstract static class FilterWrapper
     }
 
     /**
-     * If wrappers is null or empty, the file will be copy only if to.lastModified() < from.lastModified() or if
+     * If wrappers is null or empty, the file will be copy only if to.lastModified() < from.lastModified() or if
      * overwrite is true
      *
      * @param from the file to copy