You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by el...@apache.org on 2020/06/07 10:07:22 UTC
[maven-shared-utils] 01/01: clean up JavaDoc
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch apidoc
in repository https://gitbox.apache.org/repos/asf/maven-shared-utils.git
commit 8ee8dc47f43c1c5a56471a18c095003cdaf8cbac
Author: Elliotte Rusty Harold <el...@ibiblio.org>
AuthorDate: Sun Jun 7 06:07:06 2020 -0400
clean up JavaDoc
---
.../org/apache/maven/shared/utils/StringUtils.java | 191 ++++++++++-----------
1 file changed, 91 insertions(+), 100 deletions(-)
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 224c470..df9ee34 100644
--- a/src/main/java/org/apache/maven/shared/utils/StringUtils.java
+++ b/src/main/java/org/apache/maven/shared/utils/StringUtils.java
@@ -31,7 +31,7 @@ import javax.annotation.Nullable;
/**
* <p>Common <code>String</code> manipulation routines.</p>
- * <p/>
+ *
* <p>Originally from
* <a href="http://jakarta.apache.org/turbine/">Turbine</a>, the
* GenerationJavaCore library and Velocity.
@@ -57,7 +57,7 @@ public class StringUtils
* <p><code>StringUtils</code> instances should NOT be constructed in
* standard programming. Instead, the class should be used as
* <code>StringUtils.trim(" foo ");</code>.</p>
- * <p/>
+ *
* <p>This constructor is public to permit tools that require a JavaBean
* manager to operate.</p>
*/
@@ -97,13 +97,13 @@ public class StringUtils
}
/**
- * <p>Deletes all whitespaces from a String.</p>
- * <p/>
+ * <p>Deletes all whitespace from a String.</p>
+ *
* <p>Whitespace is defined by
* {@link Character#isWhitespace(char)}.</p>
*
* @param str String target to delete whitespace from
- * @return the String without whitespaces
+ * @return the String without whitespace
* @throws NullPointerException
*/
@Nonnull public static String deleteWhitespace( @Nonnull String str )
@@ -134,7 +134,7 @@ public class StringUtils
/**
* <p>Checks if a (trimmed) String is <code>null</code> or empty.</p>
- * <p/>
+ *
* <p><strong>Note:</strong> In future releases, this method will no longer trim the input string such that it works
* complementary to {@link #isNotEmpty(String)}. Code that wants to test for whitespace-only strings should be
* migrated to use {@link #isBlank(String)} instead.</p>
@@ -152,7 +152,7 @@ public class StringUtils
* <p>
* Checks if a String is whitespace, empty ("") or null.
* </p>
- * <p/>
+ *
* <pre>
* StringUtils.isBlank(null) = true
* StringUtils.isBlank("") = true
@@ -188,7 +188,7 @@ public class StringUtils
* <p>
* Checks if a String is not empty (""), not null and not whitespace only.
* </p>
- * <p/>
+ *
* <pre>
* StringUtils.isNotBlank(null) = false
* StringUtils.isNotBlank("") = false
@@ -211,7 +211,7 @@ public class StringUtils
/**
* <p>Compares two Strings, returning <code>true</code> if they are equal.</p>
- * <p/>
+ *
* <p><code>null</code>s are handled without exceptions. Two <code>null</code>
* references are considered to be equal. The comparison is case sensitive.</p>
*
@@ -229,7 +229,7 @@ public class StringUtils
/**
* <p>Compares two Strings, returning <code>true</code> if they are equal ignoring
* the case.</p>
- * <p/>
+ *
* <p><code>Nulls</code> are handled without exceptions. Two <code>null</code>
* references are considered equal. Comparison is case insensitive.</p>
*
@@ -246,7 +246,7 @@ public class StringUtils
/**
* <p>Find the first index of any of a set of potential substrings.</p>
- * <p/>
+ *
* <p><code>null</code> String will return <code>-1</code>.</p>
*
* @param str the String to check
@@ -283,7 +283,7 @@ public class StringUtils
/**
* <p>Find the latest index of any of a set of potential substrings.</p>
- * <p/>
+ *
* <p><code>null</code> string will return <code>-1</code>.</p>
*
* @param str the String to check
@@ -315,7 +315,7 @@ public class StringUtils
/**
* <p>Gets a substring from the specified string avoiding exceptions.</p>
- * <p/>
+ *
* <p>A negative start position can be used to start <code>n</code>
* characters from the end of the String.</p>
*
@@ -351,7 +351,7 @@ public class StringUtils
/**
* <p>Gets a substring from the specified String avoiding exceptions.</p>
- * <p/>
+ *
* <p>A negative start position can be used to start/end <code>n</code>
* characters from the end of the String.</p>
*
@@ -406,7 +406,7 @@ public class StringUtils
/**
* <p>Gets the leftmost <code>n</code> characters of a String.</p>
- * <p/>
+ *
* <p>If <code>n</code> characters are not available, or the
* String is <code>null</code>, the String will be returned without
* an exception.</p>
@@ -434,7 +434,7 @@ public class StringUtils
/**
* <p>Gets the rightmost <code>n</code> characters of a String.</p>
- * <p/>
+ *
* <p>If <code>n</code> characters are not available, or the String
* is <code>null</code>, the String will be returned without an
* exception.</p>
@@ -462,7 +462,7 @@ public class StringUtils
/**
* <p>Gets <code>n</code> characters from the middle of a String.</p>
- * <p/>
+ *
* <p>If <code>n</code> characters are not available, the remainder
* of the String will be returned without an exception. If the
* String is <code>null</code>, <code>null</code> will be returned.</p>
@@ -504,7 +504,7 @@ public class StringUtils
/**
* <p>Splits the provided text into a array, using whitespace as the
* separator.</p>
- * <p/>
+ *
* <p>The separator is not included in the returned String array.</p>
*
* @param str the String to parse
@@ -528,11 +528,11 @@ public class StringUtils
/**
* <p>Splits the provided text into a array, based on a given separator.</p>
- * <p/>
+ *
* <p>The separator is not included in the returned String array. The
* maximum number of splits to perform can be controlled. A <code>null</code>
* separator causes splitting on whitespace.</p>
- * <p/>
+ *
* <p>This is useful for quickly splitting a String into
* an array of tokens, instead of an enumeration of tokens (as
* <code>StringTokenizer</code> does).</p>
@@ -596,7 +596,7 @@ public class StringUtils
/**
* <p>Concatenates elements of an array into a single String.</p>
- * <p/>
+ *
* <p>The difference from join is that concatenate has no delimiter.</p>
*
* @param array the array of values to concatenate.
@@ -610,7 +610,7 @@ public class StringUtils
/**
* <p>Joins the elements of the provided array into a single String
* containing the provided list of elements.</p>
- * <p/>
+ *
* <p>No delimiter is added before or after the list. A
* <code>null</code> separator is the same as a blank String.</p>
*
@@ -642,7 +642,7 @@ public class StringUtils
/**
* <p>Joins the elements of the provided <code>Iterator</code> into
* a single String containing the provided elements.</p>
- * <p/>
+ *
* <p>No delimiter is added before or after the list. A
* <code>null</code> separator is the same as a blank String.</p>
*
@@ -673,7 +673,7 @@ public class StringUtils
/**
* <p>Replace a char with another char inside a larger String, once.</p>
- * <p/>
+ *
* <p>A <code>null</code> reference passed to this method is a no-op.</p>
*
* @param text text to search and replace in
@@ -689,7 +689,7 @@ public class StringUtils
/**
* <p>Replace all occurances of a char within another char.</p>
- * <p/>
+ *
* <p>A <code>null</code> reference passed to this method is a no-op.</p>
*
* @param text text to search and replace in
@@ -706,7 +706,7 @@ public class StringUtils
/**
* <p>Replace a char with another char inside a larger String,
* for the first <code>max</code> values of the search char.</p>
- * <p/>
+ *
* <p>A <code>null</code> reference passed to this method is a no-op.</p>
*
* @param text text to search and replace in
@@ -722,7 +722,7 @@ public class StringUtils
/**
* <p>Replace a String with another String inside a larger String, once.</p>
- * <p/>
+ *
* <p>A <code>null</code> reference passed to this method is a no-op.</p>
*
* @param text text to search and replace in
@@ -737,8 +737,8 @@ public class StringUtils
}
/**
- * <p>Replace all occurances of a String within another String.</p>
- * <p/>
+ * <p>Replace all occurrences of a String within another String.</p>
+ *
* <p>A <code>null</code> reference passed to this method is a no-op.</p>
*
* @param text text to search and replace in
@@ -755,7 +755,7 @@ public class StringUtils
/**
* <p>Replace a String with another String inside a larger String,
* for the first <code>max</code> values of the search String.</p>
- * <p/>
+ *
* <p>A <code>null</code> reference passed to this method is a no-op.</p>
*
* @param text text to search and replace in
@@ -815,7 +815,7 @@ public class StringUtils
/**
* <p>Center a String in a larger String of size <code>n</code>.<p>
- * <p/>
+ *
* <p>Uses spaces as the value to buffer the String with.
* Equivalent to <code>center(str, size, " ")</code>.</p>
*
@@ -831,7 +831,7 @@ public class StringUtils
/**
* <p>Center a String in a larger String of size <code>n</code>.</p>
- * <p/>
+ *
* <p>Uses a supplied String as the value to buffer the String with.</p>
*
* @param str String to center
@@ -1004,7 +1004,7 @@ public class StringUtils
/**
* <p>Remove the last character from a String.</p>
- * <p/>
+ *
* <p>If the String ends in <code>\r\n</code>, then remove both
* of them.</p>
*
@@ -1068,7 +1068,7 @@ public class StringUtils
/**
* <p>Escapes any values it finds into their String form.</p>
- * <p/>
+ *
* <p>So a tab becomes the characters <code>'\\'</code> and
* <code>'t'</code>.</p>
*
@@ -1187,7 +1187,7 @@ public class StringUtils
/**
* <p>Right pad a String with spaces.</p>
- * <p/>
+ *
* <p>The String is padded to the size of <code>n</code>.</p>
*
* @param str String to repeat
@@ -1202,7 +1202,7 @@ public class StringUtils
/**
* <p>Right pad a String with a specified string.</p>
- * <p/>
+ *
* <p>The String is padded to the size of <code>n</code>.</p>
*
* @param str String to pad out
@@ -1224,7 +1224,7 @@ public class StringUtils
/**
* <p>Left pad a String with spaces.</p>
- * <p/>
+ *
* <p>The String is padded to the size of <code>n</code>.</p>
*
* @param str String to pad out
@@ -1274,7 +1274,7 @@ public class StringUtils
/**
* <p>Remove a specified String from the front and back of a
* String.</p>
- * <p/>
+ *
* <p>If whitespace is wanted to be removed, used the
* {@link #strip(java.lang.String)} method.</p>
*
@@ -1325,7 +1325,7 @@ public class StringUtils
/**
* <p>Strip any of a supplied String from the end of a String.</p>
- * <p/>
+ *
* <p>If the strip String is <code>null</code>, whitespace is
* stripped.</p>
*
@@ -1360,7 +1360,7 @@ public class StringUtils
/**
* <p>Strip any of a supplied String from the start of a String.</p>
- * <p/>
+ *
* <p>If the strip String is <code>null</code>, whitespace is
* stripped.</p>
*
@@ -1433,7 +1433,7 @@ public class StringUtils
/**
* <p>Uncapitalise a String.</p>
- * <p/>
+ *
* <p>That is, convert the first character into lower-case.
* <code>null</code> is returned as <code>null</code>.</p>
*
@@ -1465,7 +1465,7 @@ public class StringUtils
/**
* <p>Capitalise a String.</p>
- * <p/>
+ *
* <p>That is, convert the first character into title-case.
* <code>null</code> is returned as <code>null</code>.</p>
*
@@ -1497,10 +1497,10 @@ public class StringUtils
/**
* <p>Swaps the case of String.</p>
- * <p/>
+ *
* <p>Properly looks after making sure the start of words
* are Titlecase and not Uppercase.</p>
- * <p/>
+ *
* <p><code>null</code> is returned as <code>null</code>.</p>
*
* @param str the String to swap the case of
@@ -1554,10 +1554,10 @@ public class StringUtils
/**
* <p>Capitalise all the words in a String.</p>
- * <p/>
+ *
* <p>Uses {@link Character#isWhitespace(char)} as a
* separator between words.</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>null</code>.</p>
*
* @param str the String to capitalise
@@ -1595,10 +1595,10 @@ public class StringUtils
/**
* <p>Uncapitalise all the words in a string.</p>
- * <p/>
+ *
* <p>Uses {@link Character#isWhitespace(char)} as a
* separator between words.</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>null</code>.</p>
*
* @param str the string to uncapitalise
@@ -1640,7 +1640,7 @@ public class StringUtils
/**
* <p>Get the String that is nested in between two instances of the
* same String.</p>
- * <p/>
+ *
* <p>If <code>str</code> is <code>null</code>, will
* return <code>null</code>.</p>
*
@@ -1683,7 +1683,7 @@ public class StringUtils
/**
* <p>How many times is the substring in the larger String.</p>
- * <p/>
+ *
* <p><code>null</code> returns <code>0</code>.</p>
*
* @param str the String to check
@@ -1716,7 +1716,7 @@ public class StringUtils
/**
* <p>Checks if the String contains only Unicode letters.</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>false</code>.
* An empty String will return <code>true</code>.</p>
*
@@ -1742,7 +1742,7 @@ public class StringUtils
/**
* <p>Checks if the String contains only whitespace.</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>false</code>. An
* empty String will return <code>true</code>.</p>
*
@@ -1769,7 +1769,7 @@ public class StringUtils
/**
* <p>Checks if the String contains only Unicode letters and
* space (<code>' '</code>).</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>false</code>. An
* empty String will return <code>true</code>.</p>
*
@@ -1796,7 +1796,7 @@ public class StringUtils
/**
* <p>Checks if the String contains only Unicode letters or digits.</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>false</code>. An empty
* String will return <code>true</code>.</p>
*
@@ -1824,7 +1824,7 @@ public class StringUtils
/**
* <p>Checks if the String contains only Unicode letters, digits
* or space (<code>' '</code>).</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>false</code>. An empty
* String will return <code>true</code>.</p>
*
@@ -1851,7 +1851,7 @@ public class StringUtils
/**
* <p>Checks if the String contains only Unicode digits.</p>
- * <p/>
+ *
* <p><code>null</code> will return <code>false</code>.
* An empty String will return <code>true</code>.</p>
*
@@ -1913,7 +1913,7 @@ public class StringUtils
/**
* <p>Reverse a String.</p>
- * <p/>
+ *
* <p><code>null</code> String returns <code>null</code>.</p>
*
* @param str the String to reverse
@@ -1930,7 +1930,7 @@ public class StringUtils
/**
* <p>Reverses a String that is delimited by a specific character.</p>
- * <p/>
+ *
* <p>The Strings between the delimiters are not reversed.
* Thus java.lang.String becomes String.lang.java (if the delimiter
* is <code>'.'</code>).</p>
@@ -1950,8 +1950,6 @@ public class StringUtils
/**
* <p>Reverses an array.</p>
- * <p/>
- * <p>TAKEN FROM CollectionsUtils.</p>
*
* @param array the array to reverse
*/
@@ -2159,17 +2157,13 @@ public class StringUtils
}
/**
- * Convert the first character of the given String to uppercase.
- * This method will <i>not</i> trim of spaces!
- * <p/>
- * <p>
- * <b>Attention:</b> this method will currently throw a
- * <code>IndexOutOfBoundsException</code> for empty strings!
- * </p>
+ * Converts the first character of the given String to uppercase.
+ * This method does <i>not</i> trim spaces!
*
* @param data the String to get capitalized
* @return data string with the first character transformed to uppercase
* @throws NullPointerException if data is <code>null</code>
+ * @throws IndexOutOfBoundsException if data is empty
*/
@Nonnull public static String capitalizeFirstLetter( @Nonnull String data )
{
@@ -2186,17 +2180,14 @@ public class StringUtils
}
/**
- * Convert the first character of the given String to lowercase.
- * This method will <i>not</i> trim of spaces!
+ * Converts the first character of the given String to lowercase.
+ * This method does <i>not</i> trim spaces!
* <p/>
- * <p>
- * <b>Attention:</b> this method will currently throw a
- * <code>IndexOutOfBoundsException</code> for empty strings!
- * </p>
*
* @param data the String to get it's first character lower-cased.
* @return data string with the first character transformed to lowercase
* @throws NullPointerException if data is <code>null</code>
+ * @throws IndexOutOfBoundsException if data is empty
*/
@Nonnull public static String lowercaseFirstLetter( @Nonnull String data )
{
@@ -2212,7 +2203,7 @@ public class StringUtils
* <p/>
* 'ThisIsIt' will become 'this-is-it'.
*
- * @param view The view.
+ * @param view the view
* @return deHumped String
*/
@Nonnull public static String addAndDeHump( @Nonnull String view )
@@ -2234,7 +2225,7 @@ public class StringUtils
/**
* <p>Quote and escape a String with the given character, handling <code>null</code>.</p>
- * <p/>
+ *
* <pre>
* StringUtils.quoteAndEscape(null, *) = null
* StringUtils.quoteAndEscape("", *) = ""
@@ -2258,9 +2249,9 @@ public class StringUtils
/**
* <p>Quote and escape a String with the given character, handling <code>null</code>.</p>
*
- * @param source The source.
- * @param quoteChar The quote character.
- * @param quotingTriggers The quoting trigger.
+ * @param source the source
+ * @param quoteChar the quote character
+ * @param quotingTriggers the quoting trigger
* @return the String quoted and escaped
* @see #quoteAndEscape(String, char, char[], char[], char, boolean)
*
@@ -2271,11 +2262,11 @@ public class StringUtils
}
/**
- * @param source The source.
- * @param quoteChar The quote character.
- * @param escapedChars The escaped characters.
- * @param escapeChar The escape character.
- * @param force true/false.
+ * @param source the source
+ * @param quoteChar the quote character
+ * @param escapedChars the escaped characters
+ * @param escapeChar the escape character
+ * @param force true/false
* @return the String quoted and escaped
* @see #quoteAndEscape(String, char, char[], char[], char, boolean)
*
@@ -2287,12 +2278,12 @@ public class StringUtils
}
/**
- * @param source The source.
- * @param quoteChar The quote character.
- * @param escapedChars set of characters to escape.
- * @param quotingTriggers The quoting trigger.
- * @param escapeChar prefix for escaping a character.
- * @param force true/false.
+ * @param source the source
+ * @param quoteChar the quote character
+ * @param escapedChars set of characters to escape
+ * @param quotingTriggers the quoting trigger
+ * @param escapeChar prefix for escaping a character
+ * @param force true/false
* @return the String quoted and escaped
*/
public static String quoteAndEscape( @Nullable String source, char quoteChar, @Nonnull final char[] escapedChars,
@@ -2341,9 +2332,9 @@ public class StringUtils
}
/**
- * @param source The source.
- * @param escapedChars set of characters to escape.
- * @param escapeChar prefix for escaping a character.
+ * @param source the source
+ * @param escapedChars set of characters to escape
+ * @param escapeChar prefix for escaping a character
* @return the String escaped
*/
public static String escape( @Nullable String source, @Nonnull final char[] escapedChars, char escapeChar )
@@ -2379,7 +2370,7 @@ public class StringUtils
* space.
*
* @param s a not null String
- * @return a string with unique whitespace.
+ * @return a string with unique whitespace
*
*/
@Nonnull public static String removeDuplicateWhitespace( @Nonnull String s )
@@ -2405,7 +2396,7 @@ public class StringUtils
* '\n', '\r' and '\r\n' with the system line separator.
*
* @param s a not null String
- * @return a String that contains only System line separators.
+ * @return a String that contains only System line separators
* @see #unifyLineSeparators(String, String)
*
*/
@@ -2420,7 +2411,7 @@ public class StringUtils
*
* @param s a not null String
* @param ls the wanted line separator ("\n" on UNIX), if null using the System line separator.
- * @return a String that contains only System line separators.
+ * @return a String that contains only System line separators
* @throws IllegalArgumentException if ls is not '\n', '\r' and '\r\n' characters.
*
*/
@@ -2471,9 +2462,9 @@ public class StringUtils
/**
* <p>Checks if String contains a search character, handling <code>null</code>.
* This method uses {@link String#indexOf(int)}.</p>
- * <p/>
+ *
* <p>A <code>null</code> or empty ("") String will return <code>false</code>.</p>
- * <p/>
+ *
* <pre>
* StringUtils.contains(null, *) = false
* StringUtils.contains("", *) = false
@@ -2495,9 +2486,9 @@ public class StringUtils
/**
* <p>Checks if String contains a search String, handling <code>null</code>.
* This method uses {@link String#indexOf(int)}.</p>
- * <p/>
+ *
* <p>A <code>null</code> String will return <code>false</code>.</p>
- * <p/>
+ *
* <pre>
* StringUtils.contains(null, *) = false
* StringUtils.contains(*, null) = false
@@ -2521,7 +2512,7 @@ public class StringUtils
* <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>
- * <p/>
+ *
* <pre>
* StringUtils.endsWithIgnoreCase(null, *) = false
* StringUtils.endsWithIgnoreCase(*, null) = false