commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r1057009 - in /commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang: StringUtils.java builder/HashCodeBuilder.java math/package.html package.html reflect/FieldUtils.java reflect/MemberUtils.java text/StrSubstitutor.java
Date Sun, 09 Jan 2011 19:48:06 GMT
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



Mime
View raw message