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