Author: niallp
Date: Sun Jan 9 19:48:06 2011
New Revision: 1057009
URL: http://svn.apache.org/viewvc?rev=1057009&view=rev
Log:
Port to LANG 2.x Branch - Javadoc improvements/corrections
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/StringUtils.java
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/builder/HashCodeBuilder.java
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/math/package.html
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/package.html
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/FieldUtils.java
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/MemberUtils.java
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/text/StrSubstitutor.java
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/StringUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/StringUtils.java?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/StringUtils.java
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/StringUtils.java
Sun Jan 9 19:48:06 2011
@@ -754,6 +754,7 @@ public class StringUtils {
* StringUtils.indexOf(null, *) = -1
* StringUtils.indexOf(*, null) = -1
* StringUtils.indexOf("", "") = 0
+ * StringUtils.indexOf("", *) = -1 (except when * = "")
* StringUtils.indexOf("aabaabaa", "a") = 0
* StringUtils.indexOf("aabaabaa", "b") = 2
* StringUtils.indexOf("aabaabaa", "ab") = 1
@@ -861,6 +862,7 @@ public class StringUtils {
* StringUtils.indexOf(null, *, *) = -1
* StringUtils.indexOf(*, null, *) = -1
* StringUtils.indexOf("", "", 0) = 0
+ * StringUtils.indexOf("", *, 0) = -1 (except when * = "")
* StringUtils.indexOf("aabaabaa", "a", 0) = 0
* StringUtils.indexOf("aabaabaa", "b", 0) = 2
* StringUtils.indexOf("aabaabaa", "ab", 0) = 1
@@ -1483,13 +1485,13 @@ public class StringUtils {
* A <code>null</code> or zero length search array will return
<code>-1</code>.</p>
*
* <pre>
- * StringUtils.indexOfAnyBut(null, *) = -1
- * StringUtils.indexOfAnyBut("", *) = -1
- * StringUtils.indexOfAnyBut(*, null) = -1
- * StringUtils.indexOfAnyBut(*, []) = -1
- * StringUtils.indexOfAnyBut("zzabyycdxx",'za') = 3
- * StringUtils.indexOfAnyBut("zzabyycdxx", '') = 0
- * StringUtils.indexOfAnyBut("aba", 'ab') = -1
+ * StringUtils.indexOfAnyBut(null, *) = -1
+ * StringUtils.indexOfAnyBut("", *) = -1
+ * StringUtils.indexOfAnyBut(*, null) = -1
+ * StringUtils.indexOfAnyBut(*, []) = -1
+ * StringUtils.indexOfAnyBut("zzabyycdxx", new char[] {'z', 'a'} ) = 3
+ * StringUtils.indexOfAnyBut("aba", new char[] {'z'} ) = 0
+ * StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} ) = -1
* </pre>
*
* @param str the String to check, may be null
@@ -1529,7 +1531,7 @@ public class StringUtils {
* character not in the given set of characters.</p>
*
* <p>A <code>null</code> String will return <code>-1</code>.
- * A <code>null</code> search string will return <code>-1</code>.</p>
+ * A <code>null</code> or empty search string will return
<code>-1</code>.</p>
*
* <pre>
* StringUtils.indexOfAnyBut(null, *) = -1
@@ -1537,7 +1539,7 @@ public class StringUtils {
* StringUtils.indexOfAnyBut(*, null) = -1
* StringUtils.indexOfAnyBut(*, "") = -1
* StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3
- * StringUtils.indexOfAnyBut("zzabyycdxx", "") = 0
+ * StringUtils.indexOfAnyBut("zzabyycdxx", "") = -1
* StringUtils.indexOfAnyBut("aba","ab") = -1
* </pre>
*
@@ -1575,7 +1577,7 @@ public class StringUtils {
*
* <p>A <code>null</code> String will return <code>false</code>.
* A <code>null</code> valid character array will return
<code>false</code>.
- * An empty String ("") always returns <code>true</code>.</p>
+ * An empty String (length()=0) always returns <code>true</code>.</p>
*
* <pre>
* StringUtils.containsOnly(null, *) = false
@@ -1610,7 +1612,7 @@ public class StringUtils {
*
* <p>A <code>null</code> String will return <code>false</code>.
* A <code>null</code> valid character String will return
<code>false</code>.
- * An empty String ("") always returns <code>true</code>.</p>
+ * An empty String (length()=0) always returns <code>true</code>.</p>
*
* <pre>
* StringUtils.containsOnly(null, *) = false
@@ -1641,7 +1643,7 @@ public class StringUtils {
*
* <p>A <code>null</code> String will return <code>true</code>.
* A <code>null</code> invalid character array will return
<code>true</code>.
- * An empty String ("") always returns true.</p>
+ * An empty String (length()=0) always returns true.</p>
*
* <pre>
* StringUtils.containsNone(null, *) = true
@@ -3093,8 +3095,10 @@ public class StringUtils {
// Joining
//-----------------------------------------------------------------------
/**
- * <p>Concatenates elements of an array into a single String.
- * Null objects or empty strings within the array are represented by
+ * <p>Joins the provided elements into a single String. </p>
+ *
+ * <p>No separator is added to the joined String.
+ * Null objects or empty string elements are represented by
* empty strings.</p>
*
* <pre>
@@ -5328,7 +5332,7 @@ public class StringUtils {
* <p>Checks if the String contains only unicode letters.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isAlpha(null) = false
@@ -5360,7 +5364,7 @@ public class StringUtils {
* space (' ').</p>
*
* <p><code>null</code> will return <code>false</code>
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isAlphaSpace(null) = false
@@ -5393,7 +5397,7 @@ public class StringUtils {
* <p>Checks if the String contains only unicode letters or digits.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isAlphanumeric(null) = false
@@ -5427,7 +5431,7 @@ public class StringUtils {
* or space (<code>' '</code>).</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isAlphanumeric(null) = false
@@ -5460,7 +5464,7 @@ public class StringUtils {
* <p>Checks if the string contains only ASCII printable characters.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isAsciiPrintable(null) = false
@@ -5499,7 +5503,7 @@ public class StringUtils {
* A decimal point is not a unicode digit and returns false.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isNumeric(null) = false
@@ -5534,7 +5538,7 @@ public class StringUtils {
* A decimal point is not a unicode digit and returns false.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isNumeric(null) = false
@@ -5568,7 +5572,7 @@ public class StringUtils {
* <p>Checks if the String contains only whitespace.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>true</code>.</p>
+ * An empty String (length()=0) will return <code>true</code>.</p>
*
* <pre>
* StringUtils.isWhitespace(null) = false
@@ -5600,7 +5604,7 @@ public class StringUtils {
* <p>Checks if the String contains only lowercase characters.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>false</code>.</p>
+ * An empty String (length()=0) will return <code>false</code>.</p>
*
* <pre>
* StringUtils.isAllLowerCase(null) = false
@@ -5631,7 +5635,7 @@ public class StringUtils {
* <p>Checks if the String contains only uppercase characters.</p>
*
* <p><code>null</code> will return <code>false</code>.
- * An empty String ("") will return <code>false</code>.</p>
+ * An empty String (length()=0) will return <code>false</code>.</p>
*
* <pre>
* StringUtils.isAllUpperCase(null) = false
@@ -5734,11 +5738,11 @@ public class StringUtils {
* StringUtils.defaultIfEmpty("", null) = null
* </pre>
*
- * @see StringUtils#defaultString(String, String)
* @param str the String to check, may be null
* @param defaultStr the default String to return
* if the input is empty ("") or <code>null</code>, may be null
* @return the passed in String, or the default
+ * @see StringUtils#defaultString(String, String)
*/
public static String defaultIfEmpty(String str, String defaultStr) {
return StringUtils.isEmpty(str) ? defaultStr : str;
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/builder/HashCodeBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/builder/HashCodeBuilder.java?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/builder/HashCodeBuilder.java
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/builder/HashCodeBuilder.java
Sun Jan 9 19:48:06 2011
@@ -38,6 +38,13 @@ import org.apache.commons.lang.ArrayUtil
* </p>
*
* <p>
+ * The following is the approach taken. When appending a data field, the
current total is multiplied by the
+ * multiplier then a relevant value
+ * for that data type is added. For example, if the current hashCode is 17,
and the multiplier is 37, then
+ * appending the integer 45 will create a hashcode of 674, namely 17 * 37 +
45.
+ * </p>
+ *
+ * <p>
* All relevant fields from the object should be included in the
<code>hashCode</code> method. Derived fields may be
* excluded. In general, any field used in the <code>equals</code> method must
be used in the <code>hashCode</code>
* method.
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/math/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/math/package.html?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/math/package.html
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/math/package.html
Sun Jan 9 19:48:06 2011
@@ -17,7 +17,8 @@ limitations under the License.
<html>
<body>
Extends {...@link java.math} for business mathematical classes. This package
is intended for business
-mathematical use, not scientific use.
+mathematical use, not scientific use. See <a
href="http://commons.apache.org/math/";>Commons Math</a>
+for a more complete set of mathematical classes.
@since 2.0
<p>These classes are immutable, and therefore thread-safe.</p>
</body>
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/package.html?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/package.html
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/package.html
Sun Jan 9 19:48:06 2011
@@ -17,7 +17,7 @@ limitations under the License.
<html>
<body>
Provides highly reusable static utility methods, chiefly concerned
-with adding value to {...@link java.lang} and other standard core classes.
+with adding value to the {...@link java.lang} classes.
@since 1.0
<p>Most of these classes are immutable and thus thread-safe.
However Charset is not currently guaranteed thread-safe under all
circumstances.</p>
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/FieldUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/FieldUtils.java?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/FieldUtils.java
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/FieldUtils.java
Sun Jan 9 19:48:06 2011
@@ -48,7 +48,7 @@ public class FieldUtils {
}
/**
- * Gets an accessible <code>Field</code> by name repecting scope.
+ * Gets an accessible <code>Field</code> by name respecting scope.
* Superclasses/interfaces will be considered.
*
* @param cls the class to reflect, must not be null
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/MemberUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/MemberUtils.java?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/MemberUtils.java
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/reflect/MemberUtils.java
Sun Jan 9 19:48:06 2011
@@ -27,7 +27,8 @@ import org.apache.commons.lang.SystemUti
/**
* Contains common code for working with Methods/Constructors, extracted and
- * refactored from <code>MethodUtils</code> when it was imported from Commons
BeanUtils.
+ * refactored from <code>MethodUtils</code> when it was imported from Commons
+ * BeanUtils.
*
* @author Apache Software Foundation
* @author Steve Cohen
@@ -62,13 +63,13 @@ abstract class MemberUtils {
/**
* XXX Default access superclass workaround
*
- * When a public class has a default access superclass with public
- * members, these members are accessible. Calling them from
- * compiled code works fine. Unfortunately, on some JVMs, using reflection
to invoke these
- * members seems to (wrongly) to prevent access even when the
- * modifer is public. Calling setAccessible(true) solves the problem
- * but will only work from sufficiently privileged code. Better
- * workarounds would be gratefully accepted.
+ * When a public class has a default access superclass with public members,
+ * these members are accessible. Calling them from compiled code works
fine.
+ * Unfortunately, on some JVMs, using reflection to invoke these members
+ * seems to (wrongly) to prevent access even when the modifer is public.
+ * Calling setAccessible(true) solves the problem but will only work from
+ * sufficiently privileged code. Better workarounds would be gratefully
+ * accepted.
* @param o the AccessibleObject to set as accessible
*/
static void setAccessibleWorkaround(AccessibleObject o) {
@@ -122,11 +123,13 @@ abstract class MemberUtils {
/**
* Compare the relative fitness of two sets of parameter types in terms of
* matching a third set of runtime parameter types, such that a list
ordered
- * by the results of the comparison would return the best match first
(least).
+ * by the results of the comparison would return the best match first
+ * (least).
*
* @param left the "left" parameter set
* @param right the "right" parameter set
- * @param actual the runtime parameter types to match against
<code>left</code>/<code>right</code>
+ * @param actual the runtime parameter types to match against
+ * <code>left</code>/<code>right</code>
* @return int consistent with <code>compare</code> semantics
*/
static int compareParameterTypes(Class[] left, Class[] right, Class[]
actual) {
@@ -136,8 +139,8 @@ abstract class MemberUtils {
}
/**
- * Returns the sum of the object transformation cost for each class in the
source
- * argument list.
+ * Returns the sum of the object transformation cost for each class in the
+ * source argument list.
* @param srcArgs The source arguments
* @param destArgs The destination arguments
* @return The total transformation cost
@@ -155,9 +158,9 @@ abstract class MemberUtils {
}
/**
- * Gets the number of steps required needed to turn the source class into
the
- * destination class. This represents the number of steps in the object
hierarchy
- * graph.
+ * Gets the number of steps required needed to turn the source class into
+ * the destination class. This represents the number of steps in the object
+ * hierarchy graph.
* @param srcClass The source class
* @param destClass The destination class
* @return The cost of transforming an object
@@ -193,7 +196,8 @@ abstract class MemberUtils {
}
/**
- * Get the number of steps required to promote a primitive number to
another type.
+ * Get the number of steps required to promote a primitive number to
another
+ * type.
* @param srcClass the (primitive) source class
* @param destClass the (primitive) destination class
* @return The cost of promoting the primitive
Modified:
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/text/StrSubstitutor.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/text/StrSubstitutor.java?rev=1057009&r1=1057008&r2=1057009&view=diff
==============================================================================
---
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/text/StrSubstitutor.java
(original)
+++
commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/text/StrSubstitutor.java
Sun Jan 9 19:48:06 2011
@@ -73,7 +73,7 @@ import java.util.Properties;
* <pre>
* The variable ${${name}} must be used.
* </pre>
- * Here only the variable's name refered to in the text should be replaced
resulting
+ * 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</code> variable is
<code>x</code>):
* <pre>
* The variable ${x} must be used.
@@ -784,7 +784,7 @@ public class StrSubstitutor {
/**
* Sets the variable prefix to use.
* <p>
- * The variable prefix is the characer or characters that identify the
+ * 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.
*
@@ -863,7 +863,7 @@ public class StrSubstitutor {
/**
* Sets the variable suffix to use.
* <p>
- * The variable suffix is the characer or characters that identify the
+ * 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.
*
* @param suffix the suffix for variables, not null
