You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2022/06/14 12:39:14 UTC
[commons-lang] branch master updated: Close HTML tags
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new dc8920206 Close HTML tags
dc8920206 is described below
commit dc8920206e6a63f38c87f8f30d78fb068c74172e
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Tue Jun 14 08:39:04 2022 -0400
Close HTML tags
Remove useless inline comments.
---
.../org/apache/commons/lang3/text/StrBuilder.java | 49 +++++++++++++++++++
.../org/apache/commons/lang3/text/StrLookup.java | 10 ++++
.../org/apache/commons/lang3/text/StrMatcher.java | 8 ++++
.../apache/commons/lang3/text/StrSubstitutor.java | 56 ++++++++++++++++++----
.../apache/commons/lang3/text/StrTokenizer.java | 26 ++++++++--
5 files changed, 136 insertions(+), 13 deletions(-)
diff --git a/src/main/java/org/apache/commons/lang3/text/StrBuilder.java b/src/main/java/org/apache/commons/lang3/text/StrBuilder.java
index b261059a4..0becdf394 100644
--- a/src/main/java/org/apache/commons/lang3/text/StrBuilder.java
+++ b/src/main/java/org/apache/commons/lang3/text/StrBuilder.java
@@ -67,10 +67,12 @@ import org.apache.commons.lang3.builder.Builder;
* with invalid indices or null input, have been altered - see individual methods.
* The biggest of these changes is that by default, null will not output the text
* 'null'. This can be controlled by a property, {@link #setNullText(String)}.
+ * </p>
* <p>
* Prior to 3.0, this class implemented Cloneable but did not implement the
* clone method so could not be used. From 3.0 onwards it no longer implements
* the interface.
+ * </p>
*
* @since 2.2
* @deprecated As of 3.6, use Apache Commons Text
@@ -256,6 +258,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method is the same as {@link #length()} and is provided to match the
* API of Collections.
+ * </p>
*
* @return the length
*/
@@ -268,6 +271,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method is the same as checking {@link #length()} and is provided to match the
* API of Collections.
+ * </p>
*
* @return {@code true} if the size is {@code 0}.
*/
@@ -280,6 +284,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method is the same as checking {@link #length()} and is provided to match the
* API of Collections.
+ * </p>
*
* @return {@code true} if the size is greater than {@code 0}.
* @since 3.12.0
@@ -293,9 +298,11 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method does not reduce the size of the internal character buffer.
* To do that, call {@code clear()} followed by {@link #minimizeCapacity()}.
+ * </p>
* <p>
* This method is the same as {@link #setLength(int)} called with zero
* and is provided to match the API of Collections.
+ * </p>
*
* @return this, to enable chaining
*/
@@ -476,6 +483,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* The new line string can be altered using {@link #setNewLineText(String)}.
* This might be used to force the output to always use Unix line endings
* even when on Windows.
+ * </p>
*
* @return this, to enable chaining
*/
@@ -1315,14 +1323,17 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method is useful for adding a separator each time around the
* loop except the first.
+ * </p>
* <pre>
* for (Iterator it = list.iterator(); it.hasNext(); ) {
* appendSeparator(",");
* append(it.next());
* }
* </pre>
+ * <p>
* Note that for this simple example, you should use
* {@link #appendWithSeparators(Iterable, String)}.
+ * </p>
*
* @param separator the separator to use, null means no separator
* @return this, to enable chaining
@@ -1341,6 +1352,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* The separator is appended using {@link #append(String)}.
* <p>
* This method is for example useful for constructing queries
+ * </p>
* <pre>
* StrBuilder whereClause = new StrBuilder();
* if (searchCommand.getPriority() != null) {
@@ -1373,6 +1385,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method is useful for adding a separator each time around the
* loop except the first.
+ * </p>
* <pre>
* for (Iterator it = list.iterator(); it.hasNext(); ) {
* appendSeparator(',');
@@ -1885,6 +1898,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced deletion behavior.
* For example you could write a matcher to delete all occurrences
* where the character 'a' is followed by a number.
+ * </p>
*
* @param matcher the matcher to use to find the deletion, null causes no action
* @return this, to enable chaining
@@ -1899,6 +1913,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced deletion behavior.
* For example you could write a matcher to delete
* where the character 'a' is followed by a number.
+ * </p>
*
* @param matcher the matcher to use to find the deletion, null causes no action
* @return this, to enable chaining
@@ -2031,6 +2046,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced replace behavior.
* For example you could write a matcher to replace all occurrences
* where the character 'a' is followed by a number.
+ * </p>
*
* @param matcher the matcher to use to find the deletion, null causes no action
* @param replaceStr the replace string, null is equivalent to an empty string
@@ -2046,6 +2062,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced replace behavior.
* For example you could write a matcher to replace
* where the character 'a' is followed by a number.
+ * </p>
*
* @param matcher the matcher to use to find the deletion, null causes no action
* @param replaceStr the replace string, null is equivalent to an empty string
@@ -2061,6 +2078,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced behavior.
* For example you could write a matcher to delete all occurrences
* where the character 'a' is followed by a number.
+ * </p>
*
* @param matcher the matcher to use to find the deletion, null causes no action
* @param replaceStr the string to replace the match with, null is a delete
@@ -2084,6 +2102,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced behavior.
* For example you could write a matcher to delete all occurrences
* where the character 'a' is followed by a number.
+ * </p>
*
* @param matcher the matcher to use to find the deletion, null causes no action
* @param replaceStr the string to replace the match with, null is a delete
@@ -2167,6 +2186,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Checks whether this builder starts with the specified string.
* <p>
* Note that this method handles null input quietly, unlike String.
+ * </p>
*
* @param str the string to search for, null returns false
* @return true if the builder starts with the string
@@ -2194,6 +2214,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Checks whether this builder ends with the specified string.
* <p>
* Note that this method handles null input quietly, unlike String.
+ * </p>
*
* @param str the string to search for, null returns false
* @return true if the builder ends with the string
@@ -2253,6 +2274,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Note: This method treats an endIndex greater than the length of the
* builder as equal to the length of the builder, and continues
* without error, unlike StringBuffer or String.
+ * </p>
*
* @param startIndex the start index, inclusive, must be valid
* @param endIndex the end index, exclusive, must be valid except
@@ -2273,6 +2295,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* the builder. If this many characters are not available, the whole
* builder is returned. Thus the returned string may be shorter than the
* length requested.
+ * </p>
*
* @param length the number of characters to extract, negative returns empty string
* @return the new string
@@ -2295,6 +2318,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* the builder. If this many characters are not available, the whole
* builder is returned. Thus the returned string may be shorter than the
* length requested.
+ * </p>
*
* @param length the number of characters to extract, negative returns empty string
* @return the new string
@@ -2320,6 +2344,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* If the length is negative, the empty string is returned.
* If insufficient characters are available in the builder, as much as possible is returned.
* Thus the returned string may be shorter than the length requested.
+ * </p>
*
* @param index the index to start at, negative means zero
* @param length the number of characters to extract, negative returns empty string
@@ -2371,6 +2396,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced searching behavior.
* For example you could write a matcher to search for the character
* 'a' followed by a number.
+ * </p>
*
* @param matcher the matcher to use, null returns -1
* @return true if the matcher finds a match in the builder
@@ -2414,6 +2440,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Searches the string builder to find the first reference to the specified string.
* <p>
* Note that a null input string will return -1, whereas the JDK throws an exception.
+ * </p>
*
* @param str the string to find, null returns -1
* @return the first index of the string, or -1 if not found
@@ -2427,6 +2454,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* string starting searching from the given index.
* <p>
* Note that a null input string will return -1, whereas the JDK throws an exception.
+ * </p>
*
* @param str the string to find, null returns -1
* @param startIndex the index to start at, invalid index rounded to edge
@@ -2467,6 +2495,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced searching behavior.
* For example you could write a matcher to find the character 'a'
* followed by a number.
+ * </p>
*
* @param matcher the matcher to use, null returns -1
* @return the first index matched, or -1 if not found
@@ -2482,6 +2511,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced searching behavior.
* For example you could write a matcher to find the character 'a'
* followed by a number.
+ * </p>
*
* @param matcher the matcher to use, null returns -1
* @param startIndex the index to start at, invalid index rounded to edge
@@ -2536,6 +2566,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Searches the string builder to find the last reference to the specified string.
* <p>
* Note that a null input string will return -1, whereas the JDK throws an exception.
+ * </p>
*
* @param str the string to find, null returns -1
* @return the last index of the string, or -1 if not found
@@ -2549,6 +2580,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* string starting searching from the given index.
* <p>
* Note that a null input string will return -1, whereas the JDK throws an exception.
+ * </p>
*
* @param str the string to find, null returns -1
* @param startIndex the index to start at, invalid index rounded to edge
@@ -2587,6 +2619,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced searching behavior.
* For example you could write a matcher to find the character 'a'
* followed by a number.
+ * </p>
*
* @param matcher the matcher to use, null returns -1
* @return the last index matched, or -1 if not found
@@ -2602,6 +2635,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* Matchers can be used to perform advanced searching behavior.
* For example you could write a matcher to find the character 'a'
* followed by a number.
+ * </p>
*
* @param matcher the matcher to use, null returns -1
* @param startIndex the index to start at, invalid index rounded to edge
@@ -2629,12 +2663,14 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* The tokenizer will be setup by default to tokenize on space, tab,
* newline and formfeed (as per StringTokenizer). These values can be
* changed on the tokenizer class, before retrieving the tokens.
+ * </p>
* <p>
* The returned tokenizer is linked to this builder. You may intermix
* calls to the builder and tokenizer within certain limits, however
* there is no synchronization. Once the tokenizer has been used once,
* it must be {@link StrTokenizer#reset() reset} to pickup the latest
* changes in the builder. For example:
+ * </p>
* <pre>
* StrBuilder b = new StrBuilder();
* b.append("a b ");
@@ -2645,12 +2681,15 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* t.reset(); // reset causes builder changes to be picked up
* String[] tokens3 = t.getTokenArray(); // returns a,b,c,d
* </pre>
+ * <p>
* In addition to simply intermixing appends and tokenization, you can also
* call the set methods on the tokenizer to alter how it tokenizes. Just
* remember to call reset when you want to pickup builder changes.
+ * </p>
* <p>
* Calling {@link StrTokenizer#reset(String)} or {@link StrTokenizer#reset(char[])}
* with a non-null value will break the link with the builder.
+ * </p>
*
* @return a tokenizer that is linked to this builder
*/
@@ -2663,17 +2702,21 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method allows the contents of the builder to be read
* using any standard method that expects a Reader.
+ * </p>
* <p>
* To use, simply create a {@code StrBuilder}, populate it with
* data, call {@code asReader}, and then read away.
+ * </p>
* <p>
* The internal character array is shared between the builder and the reader.
* This allows you to append to the builder after creating the reader,
* and the changes will be picked up.
* Note however, that no synchronization occurs, so you must perform
* all operations with the builder and the reader in one thread.
+ * </p>
* <p>
* The returned reader supports marking, and ignores the flush method.
+ * </p>
*
* @return a reader that reads from this builder
*/
@@ -2686,18 +2729,22 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* This method allows you to populate the contents of the builder
* using any standard method that takes a Writer.
+ * </p>
* <p>
* To use, simply create a {@code StrBuilder},
* call {@code asWriter}, and populate away. The data is available
* at any time using the methods of the {@code StrBuilder}.
+ * </p>
* <p>
* The internal character array is shared between the builder and the writer.
* This allows you to intermix calls that append to the builder and
* write using the writer and the changes will be occur correctly.
* Note however, that no synchronization occurs, so you must perform
* all operations with the builder and the writer in one thread.
+ * </p>
* <p>
* The returned writer ignores the close and flush methods.
+ * </p>
*
* @return a writer that populates this builder
*/
@@ -2710,6 +2757,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* provided {@link Appendable}.
* <p>
* This method tries to avoid doing any extra copies of contents.
+ * </p>
*
* @param appendable the appendable to append data to
* @throws IOException if an I/O error occurs
@@ -2817,6 +2865,7 @@ public class StrBuilder implements CharSequence, Appendable, Serializable, Build
* <p>
* Note that unlike StringBuffer, the string version returned is
* independent of the string builder.
+ * </p>
*
* @return the builder as a String
*/
diff --git a/src/main/java/org/apache/commons/lang3/text/StrLookup.java b/src/main/java/org/apache/commons/lang3/text/StrLookup.java
index aef5268b4..11410a715 100644
--- a/src/main/java/org/apache/commons/lang3/text/StrLookup.java
+++ b/src/main/java/org/apache/commons/lang3/text/StrLookup.java
@@ -24,12 +24,15 @@ import java.util.Map;
* This class represents the simplest form of a string to string map.
* It has a benefit over a map in that it can create the result on
* demand based on the key.
+ * </p>
* <p>
* This class comes complete with various factory methods.
* If these do not suffice, you can subclass and implement your own matcher.
+ * </p>
* <p>
* For example, it would be possible to implement a lookup that used the
* key as a primary key, and looked up the value on demand from the database.
+ * </p>
*
* @param <V> Unused.
* @since 2.2
@@ -65,8 +68,10 @@ public abstract class StrLookup<V> {
* <p>
* If a security manager blocked access to system properties, then null will
* be returned from every lookup.
+ * </p>
* <p>
* If a null key is used, this lookup will throw a NullPointerException.
+ * </p>
*
* @return a lookup using system properties, not null
*/
@@ -79,6 +84,7 @@ public abstract class StrLookup<V> {
* <p>
* If the map is null, then null will be returned from every lookup.
* The map result object is converted to a string using toString().
+ * </p>
*
* @param <V> the type of the values supported by the lookup
* @param map the map of keys to values, may be null
@@ -100,15 +106,18 @@ public abstract class StrLookup<V> {
* The internal implementation may use any mechanism to return the value.
* The simplest implementation is to use a Map. However, virtually any
* implementation is possible.
+ * </p>
* <p>
* For example, it would be possible to implement a lookup that used the
* key as a primary key, and looked up the value on demand from the database
* Or, a numeric based implementation could be created that treats the key
* as an integer, increments the value and return the result as a string -
* converting 1 to 2, 15 to 16 etc.
+ * </p>
* <p>
* The {@link #lookup(String)} method always returns a String, regardless of
* the underlying data, by converting it as necessary. For example:
+ * </p>
* <pre>
* Map<String, Object> map = new HashMap<String, Object>();
* map.put("number", Integer.valueOf(2));
@@ -143,6 +152,7 @@ public abstract class StrLookup<V> {
* <p>
* If the map is null, then null is returned.
* The map result object is converted to a string using toString().
+ * </p>
*
* @param key the key to be looked up, may be null
* @return the matching value, null if no match
diff --git a/src/main/java/org/apache/commons/lang3/text/StrMatcher.java b/src/main/java/org/apache/commons/lang3/text/StrMatcher.java
index 485cdb9d8..8d903a9da 100644
--- a/src/main/java/org/apache/commons/lang3/text/StrMatcher.java
+++ b/src/main/java/org/apache/commons/lang3/text/StrMatcher.java
@@ -27,6 +27,7 @@ import org.apache.commons.lang3.StringUtils;
* <p>
* This class comes complete with various factory methods.
* If these do not suffice, you can subclass and implement your own matcher.
+ * </p>
*
* @since 2.2
* @deprecated As of 3.6, use Apache Commons Text
@@ -225,16 +226,20 @@ public abstract class StrMatcher {
* checked in the string {@code buffer} (a character array which must
* not be changed).
* The API guarantees that {@code pos} is a valid index for {@code buffer}.
+ * </p>
* <p>
* The character array may be larger than the active area to be matched.
* Only values in the buffer between the specified indices may be accessed.
+ * </p>
* <p>
* The matching code may check one character or many.
* It may check characters preceding {@code pos} as well as those
* after, so long as no checks exceed the bounds specified.
+ * </p>
* <p>
* It must return zero for no match, or a positive number if a match was found.
* The number indicates the number of characters that matched.
+ * </p>
*
* @param buffer the text content to match against, do not change
* @param pos the starting position for the match, valid for buffer
@@ -252,12 +257,15 @@ public abstract class StrMatcher {
* checked in the string {@code buffer} (a character array which must
* not be changed).
* The API guarantees that {@code pos} is a valid index for {@code buffer}.
+ * </p>
* <p>
* The matching code may check one character or many.
* It may check characters preceding {@code pos} as well as those after.
+ * </p>
* <p>
* It must return zero for no match, or a positive number if a match was found.
* The number indicates the number of characters that matched.
+ * </p>
*
* @param buffer the text content to match against, do not change
* @param pos the starting position for the match, valid for buffer
diff --git a/src/main/java/org/apache/commons/lang3/text/StrSubstitutor.java b/src/main/java/org/apache/commons/lang3/text/StrSubstitutor.java
index 5c18bb8bf..8b9c62de1 100644
--- a/src/main/java/org/apache/commons/lang3/text/StrSubstitutor.java
+++ b/src/main/java/org/apache/commons/lang3/text/StrSubstitutor.java
@@ -31,11 +31,14 @@ import org.apache.commons.lang3.StringUtils;
* This class takes a piece of text and substitutes all the variables within it.
* The default definition of a variable is {@code ${variableName}}.
* The prefix and suffix can be changed via constructors and set methods.
+ * </p>
* <p>
* Variable values are typically resolved from a map, but could also be resolved
* from system properties, or by supplying a custom variable resolver.
+ * </p>
* <p>
* The simplest example is to use this class to replace Java System properties. For example:
+ * </p>
* <pre>
* StrSubstitutor.replaceSystemProperties(
* "You are running with java.version = ${java.version} and os.name = ${os.name}.");
@@ -48,6 +51,7 @@ import org.apache.commons.lang3.StringUtils;
* method can be called passing in the source text for interpolation. In the returned
* text all variable references (as long as their values are known) will be resolved.
* The following example demonstrates this:
+ * </p>
* <pre>
* Map valuesMap = HashMap();
* valuesMap.put("animal", "quick brown fox");
@@ -68,6 +72,7 @@ import org.apache.commons.lang3.StringUtils;
* The variable default value delimiter can be manually set by calling {@link #setValueDelimiterMatcher(StrMatcher)},
* {@link #setValueDelimiter(char)} or {@link #setValueDelimiter(String)}.
* The following shows an example with variable default value settings:
+ * </p>
* <pre>
* Map valuesMap = HashMap();
* valuesMap.put("animal", "quick brown fox");
@@ -76,7 +81,9 @@ import org.apache.commons.lang3.StringUtils;
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
* </pre>
+ * <p>
* yielding:
+ * </p>
* <pre>
* The quick brown fox jumps over the lazy dog. 1234567890.
* </pre>
@@ -85,40 +92,52 @@ import org.apache.commons.lang3.StringUtils;
* cover the most common use cases. These methods can be used without the need of
* manually creating an instance. However if multiple replace operations are to be
* performed, creating and reusing an instance of this class will be more efficient.
+ * </p>
* <p>
* Variable replacement works in a recursive way. Thus, if a variable value contains
* a variable then that variable will also be replaced. Cyclic replacements are
* detected and will cause an exception to be thrown.
+ * </p>
* <p>
* Sometimes the interpolation's result must contain a variable prefix. As an example
* take the following source text:
+ * </p>
* <pre>
* The variable ${${name}} must be used.
* </pre>
+ * <p>
* Here only the variable's name referred to in the text should be replaced resulting
* in the text (assuming that the value of the {@code name} variable is {@code x}):
+ * </p>
* <pre>
* The variable ${x} must be used.
* </pre>
+ * <p>
* To achieve this effect there are two possibilities: Either set a different prefix
* and suffix for variables which do not conflict with the result text you want to
* produce. The other possibility is to use the escape character, by default '$'.
* If this character is placed before a variable reference, this reference is ignored
* and won't be replaced. For example:
+ * </p>
* <pre>
* The variable $${${name}} must be used.
* </pre>
* <p>
* In some complex scenarios you might even want to perform substitution in the
- * names of variables, for instance
+ * names of variables, for instance:
+ * </p>
* <pre>
* ${jre-${java.specification.version}}
* </pre>
+ * <p>
* {@code StrSubstitutor} supports this recursive substitution in variable
* names, but it has to be enabled explicitly by setting the
* {@link #setEnableSubstitutionInVariables(boolean) enableSubstitutionInVariables}
* property to <b>true</b>.
- * <p>This class is <b>not</b> thread safe.</p>
+ * </p>
+ * <p>
+ * This class is <b>not</b> thread safe.
+ * </p>
*
* @since 2.2
* @deprecated As of 3.6, use Apache Commons Text
@@ -409,6 +428,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the string will be processed.
* The rest of the string is not processed, and is not returned.
+ * </p>
*
* @param source the string to replace in, null returns null
* @param offset the start offset within the array, must be valid
@@ -450,6 +470,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the array will be processed.
* The rest of the array is not processed, and is not returned.
+ * </p>
*
* @param source the character array to replace in, not altered, null returns null
* @param offset the start offset within the array, must be valid
@@ -489,6 +510,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, and is not returned.
+ * </p>
*
* @param source the buffer to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
@@ -527,6 +549,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, and is not returned.
+ * </p>
*
* @param source the buffer to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
@@ -567,6 +590,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the builder will be processed.
* The rest of the builder is not processed, and is not returned.
+ * </p>
*
* @param source the builder to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
@@ -621,6 +645,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, but it is not deleted.
+ * </p>
*
* @param source the buffer to replace in, updated, null returns zero
* @param offset the start offset within the array, must be valid
@@ -662,6 +687,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, but it is not deleted.
+ * </p>
*
* @param source the buffer to replace in, updated, null returns zero
* @param offset the start offset within the array, must be valid
@@ -701,6 +727,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the builder will be processed.
* The rest of the builder is not processed, but it is not deleted.
+ * </p>
*
* @param source the builder to replace in, null returns zero
* @param offset the start offset within the array, must be valid
@@ -719,9 +746,11 @@ public class StrSubstitutor {
* <p>
* Most users of this class do not need to call this method. This method will
* be called automatically by another (public) method.
+ * </p>
* <p>
* Writers of subclasses can override this method if they need access to
* the substitution process at the start or end.
+ * </p>
*
* @param buf the string builder to substitute into, not null
* @param offset the start offset within the builder, must be valid
@@ -901,11 +930,13 @@ public class StrSubstitutor {
* <p>
* Most users of this class do not need to call this method. This method is
* called automatically by the substitution process.
+ * </p>
* <p>
* Writers of subclasses can override this method if they need to alter
* how each substitution occurs. The method is passed the variable's name
* and must return the corresponding value. This implementation uses the
* {@link #getVariableResolver()} with the variable's name as the key.
+ * </p>
*
* @param variableName the name of the variable, not null
* @param buf the buffer where the substitution is occurring, not null
@@ -921,7 +952,6 @@ public class StrSubstitutor {
return resolver.lookup(variableName);
}
- // Escape
/**
* Returns the escape character.
*
@@ -942,13 +972,13 @@ public class StrSubstitutor {
this.escapeChar = escapeCharacter;
}
- // Prefix
/**
* Gets the variable prefix matcher currently in use.
* <p>
* The variable prefix is the character or characters that identify the
* start of a variable. This prefix is expressed in terms of a matcher
* allowing advanced prefix matches.
+ * </p>
*
* @return the prefix matcher in use
*/
@@ -962,6 +992,7 @@ public class StrSubstitutor {
* The variable prefix is the character or characters that identify the
* start of a variable. This prefix is expressed in terms of a matcher
* allowing advanced prefix matches.
+ * </p>
*
* @param prefixMatcher the prefix matcher to use, null ignored
* @return this, to enable chaining
@@ -981,6 +1012,7 @@ public class StrSubstitutor {
* The variable prefix is the character or characters that identify the
* start of a variable. This method allows a single character prefix to
* be easily set.
+ * </p>
*
* @param prefix the prefix character to use
* @return this, to enable chaining
@@ -994,6 +1026,7 @@ public class StrSubstitutor {
* <p>
* The variable prefix is the character or characters that identify the
* start of a variable. This method allows a string prefix to be easily set.
+ * </p>
*
* @param prefix the prefix for variables, not null
* @return this, to enable chaining
@@ -1006,13 +1039,13 @@ public class StrSubstitutor {
return setVariablePrefixMatcher(StrMatcher.stringMatcher(prefix));
}
- // Suffix
/**
* Gets the variable suffix matcher currently in use.
* <p>
* The variable suffix is the character or characters that identify the
* end of a variable. This suffix is expressed in terms of a matcher
* allowing advanced suffix matches.
+ * </p>
*
* @return the suffix matcher in use
*/
@@ -1026,6 +1059,7 @@ public class StrSubstitutor {
* The variable suffix is the character or characters that identify the
* end of a variable. This suffix is expressed in terms of a matcher
* allowing advanced suffix matches.
+ * </p>
*
* @param suffixMatcher the suffix matcher to use, null ignored
* @return this, to enable chaining
@@ -1045,6 +1079,7 @@ public class StrSubstitutor {
* The variable suffix is the character or characters that identify the
* end of a variable. This method allows a single character suffix to
* be easily set.
+ * </p>
*
* @param suffix the suffix character to use
* @return this, to enable chaining
@@ -1058,6 +1093,7 @@ public class StrSubstitutor {
* <p>
* The variable suffix is the character or characters that identify the
* end of a variable. This method allows a string suffix to be easily set.
+ * </p>
*
* @param suffix the suffix for variables, not null
* @return this, to enable chaining
@@ -1070,15 +1106,16 @@ public class StrSubstitutor {
return setVariableSuffixMatcher(StrMatcher.stringMatcher(suffix));
}
- // Variable Default Value Delimiter
/**
* Gets the variable default value delimiter matcher currently in use.
* <p>
* The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This delimiter is expressed in terms of a matcher
* allowing advanced variable default value delimiter matches.
+ * </p>
* <p>
* If it returns null, then the variable default value resolution is disabled.
+ * </p>
*
* @return the variable default value delimiter matcher in use, may be null
* @since 3.2
@@ -1093,9 +1130,11 @@ public class StrSubstitutor {
* The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This delimiter is expressed in terms of a matcher
* allowing advanced variable default value delimiter matches.
+ * </p>
* <p>
* If the {@code valueDelimiterMatcher} is null, then the variable default value resolution
* becomes disabled.
+ * </p>
*
* @param valueDelimiterMatcher variable default value delimiter matcher to use, may be null
* @return this, to enable chaining
@@ -1112,6 +1151,7 @@ public class StrSubstitutor {
* The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This method allows a single character
* variable default value delimiter to be easily set.
+ * </p>
*
* @param valueDelimiter the variable default value delimiter character to use
* @return this, to enable chaining
@@ -1127,9 +1167,11 @@ public class StrSubstitutor {
* The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This method allows a string
* variable default value delimiter to be easily set.
+ * </p>
* <p>
* If the {@code valueDelimiter} is null or empty string, then the variable default
* value resolution becomes disabled.
+ * </p>
*
* @param valueDelimiter the variable default value delimiter string to use, may be null or empty
* @return this, to enable chaining
@@ -1143,7 +1185,6 @@ public class StrSubstitutor {
return setValueDelimiterMatcher(StrMatcher.stringMatcher(valueDelimiter));
}
- // Resolver
/**
* Gets the VariableResolver that is used to lookup variables.
*
@@ -1162,7 +1203,6 @@ public class StrSubstitutor {
this.variableResolver = variableResolver;
}
- // Substitution support in variable names
/**
* Returns a flag whether substitution is done in variable names.
*
diff --git a/src/main/java/org/apache/commons/lang3/text/StrTokenizer.java b/src/main/java/org/apache/commons/lang3/text/StrTokenizer.java
index b4d8d72ad..4f2f97d71 100644
--- a/src/main/java/org/apache/commons/lang3/text/StrTokenizer.java
+++ b/src/main/java/org/apache/commons/lang3/text/StrTokenizer.java
@@ -35,24 +35,30 @@ import org.apache.commons.lang3.StringUtils;
* however it offers much more control and flexibility including implementing
* the {@code ListIterator} interface. By default, it is set up
* like {@code StringTokenizer}.
+ * </p>
* <p>
* The input String is split into a number of <i>tokens</i>.
* Each token is separated from the next String by a <i>delimiter</i>.
* One or more delimiter characters must be specified.
+ * </p>
* <p>
* Each token may be surrounded by quotes.
* The <i>quote</i> matcher specifies the quote character(s).
* A quote may be escaped within a quoted section by duplicating itself.
+ * </p>
* <p>
* Between each token and the delimiter are potentially characters that need trimming.
* The <i>trimmer</i> matcher specifies these characters.
* One usage might be to trim whitespace characters.
+ * </p>
* <p>
* At any point outside the quotes there might potentially be invalid characters.
* The <i>ignored</i> matcher specifies these characters to be removed.
* One usage might be to remove new line characters.
+ * </p>
* <p>
* Empty tokens may be removed or returned as null.
+ * </p>
* <pre>
* "a,b,c" - Three tokens "a","b","c" (comma delimiter)
* " a, b , c " - Three tokens "a","b","c" (default CSV processing trims whitespace)
@@ -147,6 +153,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* the setTrimmer method).
* <p>
* You must call a "reset" method to set the string which you want to parse.
+ * </p>
* @return a new tokenizer instance which parses Comma Separated Value strings
*/
public static StrTokenizer getCSVInstance() {
@@ -199,6 +206,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* (which can be overridden with the setTrimmer method).
* <p>
* You must call a "reset" method to set the string which you want to parse.
+ * </p>
* @return a new tokenizer instance which parses Tab Separated Value strings.
*/
public static StrTokenizer getTSVInstance() {
@@ -236,6 +244,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* as per StringTokenizer, but with no text to tokenize.
* <p>
* This constructor is normally used with {@link #reset(String)}.
+ * </p>
*/
public StrTokenizer() {
this.chars = null;
@@ -446,6 +455,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* Resets this tokenizer, forgetting all parsing and iteration already completed.
* <p>
* This method allows the same tokenizer to be reused for the same String.
+ * </p>
*
* @return this, to enable chaining
*/
@@ -487,7 +497,6 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
return this;
}
- // ListIterator
/**
* Checks whether there are any more tokens.
*
@@ -587,7 +596,6 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
throw new UnsupportedOperationException("add() is unsupported");
}
- // Implementation
/**
* Checks if tokenization has been done, and if not then do it.
*/
@@ -609,15 +617,18 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* <p>
* Most users of this class do not need to call this method. This method
* will be called automatically by other (public) methods when required.
+ * </p>
* <p>
* This method exists to allow subclasses to add code before or after the
* tokenization. For example, a subclass could alter the character array,
* offset or count to be parsed, or call the tokenizer multiple times on
* multiple strings. It is also be possible to filter the results.
+ * </p>
* <p>
* {@code StrTokenizer} will always pass a zero offset and a count
* equal to the length of the array to this method, however a subclass
* may pass other values, or even an entirely different array.
+ * </p>
*
* @param srcChars the character array being tokenized, may be null
* @param offset the start position within the character array, must be valid
@@ -824,7 +835,6 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
return true;
}
- // Delimiter
/**
* Gets the field delimiter matcher.
*
@@ -838,6 +848,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* Sets the field delimiter matcher.
* <p>
* The delimiter is used to separate one token from another.
+ * </p>
*
* @param delim the delimiter matcher to use
* @return this, to enable chaining
@@ -871,13 +882,13 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
return setDelimiterMatcher(StrMatcher.stringMatcher(delim));
}
- // Quote
/**
* Gets the quote matcher currently in use.
* <p>
* The quote character is used to wrap data between the tokens.
* This enables delimiters to be entered as data.
* The default value is '"' (double quote).
+ * </p>
*
* @return the quote matcher in use
*/
@@ -890,6 +901,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* <p>
* The quote character is used to wrap data between the tokens.
* This enables delimiters to be entered as data.
+ * </p>
*
* @param quote the quote matcher to use, null ignored
* @return this, to enable chaining
@@ -906,6 +918,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* <p>
* The quote character is used to wrap data between the tokens.
* This enables delimiters to be entered as data.
+ * </p>
*
* @param quote the quote character to use
* @return this, to enable chaining
@@ -921,6 +934,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* These characters are ignored when parsing the String, unless they are
* within a quoted region.
* The default value is not to ignore anything.
+ * </p>
*
* @return the ignored matcher in use
*/
@@ -933,6 +947,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* <p>
* These characters are ignored when parsing the String, unless they are
* within a quoted region.
+ * </p>
*
* @param ignored the ignored matcher to use, null ignored
* @return this, to enable chaining
@@ -957,13 +972,13 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
return setIgnoredMatcher(StrMatcher.charMatcher(ignored));
}
- // Trimmer
/**
* Gets the trimmer character matcher.
* <p>
* These characters are trimmed off on each side of the delimiter
* until the token or quote is found.
* The default value is not to trim anything.
+ * </p>
*
* @return the trimmer matcher in use
*/
@@ -976,6 +991,7 @@ public class StrTokenizer implements ListIterator<String>, Cloneable {
* <p>
* These characters are trimmed off on each side of the delimiter
* until the token or quote is found.
+ * </p>
*
* @param trimmer the trimmer matcher to use, null ignored
* @return this, to enable chaining