Javadoc changes

bug 22480, from Pete Gieser


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137607 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/lang/ArrayUtils.java

@@ -76,8 +76,9 @@
  * @author Nikolay Metchev
  * @author Matthew Hawthorne
  * @author Tim O'Brien
+ * @author Pete Gieser
  * @since 2.0
- * @version $Id: ArrayUtils.java,v 1.22 2003/08/03 23:29:19 scolebourne Exp $
+ * @version $Id: ArrayUtils.java,v 1.23 2003/08/16 11:04:46 scolebourne Exp $
  */
 public class ArrayUtils {
 
@@ -1531,6 +1532,7 @@ public static int lastIndexOf(final double[] array, final double valueToFind, in
      * @param array  the array to traverse for looking for the object, may be <code>null</code>
      * @param valueToFind  the value to find
      * @param startIndex  the start index to travers backwards from
+     * @param tolerance  search for value within plus/minus this amount
      * @return the last index of the value within the array,
      *  <code>-1</code> if not found or <code>null</code> array input
      */
@@ -1574,9 +1576,10 @@ public static boolean contains(final double[] array, final double valueToFind) {
      * <p>The method returns <code>false</code> if a <code>null</code> array
      * is passed in.</p>
      *
-     * @param array the array to search
-     * @param valueToFind the value to find
-     * @param tolerance the array contains the tolerance of the search.
+     * @param array  the array to search
+     * @param valueToFind  the value to find
+     * @param tolerance  the array contains the tolerance of the search
+     * @return true if value falling within tolerance is in array
      */
     public static boolean contains(final double[] array, final double valueToFind, final double tolerance) {
         return (indexOf(array, valueToFind, 0, tolerance) != -1);

src/java/org/apache/commons/lang/CharSet.java

@@ -68,8 +68,9 @@
  * @author Henri Yandell
  * @author Stephen Colebourne
  * @author Phil Steitz
+ * @author Pete Gieser
  * @since 1.0
- * @version $Id: CharSet.java,v 1.14 2003/08/07 21:12:19 bayard Exp $
+ * @version $Id: CharSet.java,v 1.15 2003/08/16 11:04:46 scolebourne Exp $
  */
 public class CharSet implements Serializable {
 
@@ -146,6 +147,7 @@ public class CharSet implements Serializable {
      * <p>All CharSet objects returned by this method will be immutable.</p>
      *
      * @param setStr  the String describing the set, may be null
+     * @return a CharSet instance
      */
     public static CharSet getInstance(String setStr) {
         Object set = COMMON.get(setStr);
@@ -170,6 +172,7 @@ protected CharSet(String setStr) {
      * <p>Constructs a new CharSet using the set syntax.
      * Each string is merged in with the set.</p>
      *
+     * @param set  Strings to merge into the initial set
      * @throws NullPointerException if set is <code>null</code>
      */
     protected CharSet(String[] set) {
@@ -252,7 +255,6 @@ public boolean contains(char ch) {
      * <p>The two sets <code>abc</code> and <code>a-c</code> are <i>not</i>
      * equal according to this method.</p>
      *
-     * 
      * @param obj  the object to compare to
      * @return true if equal
      */

src/java/org/apache/commons/lang/StringEscapeUtils.java

@@ -72,8 +72,9 @@
  * @author <a href="sean@boohai.com">Sean Brown</a>
  * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
  * @author Phil Steitz
+ * @author Pete Gieser
  * @since 2.0
- * @version $Id: StringEscapeUtils.java,v 1.23 2003/08/01 20:45:17 scolebourne Exp $
+ * @version $Id: StringEscapeUtils.java,v 1.24 2003/08/16 11:04:46 scolebourne Exp $
  */
 public class StringEscapeUtils {
 
@@ -308,6 +309,7 @@ public static String unescapeJava(String str) {
      * @param out  the <code>Writer</code> used to output unescaped characters
      * @param str  the <code>String</code> to unescape, may be null
      * @throws IllegalArgumentException if the Writer is <code>null</code>
+     * @throws IOException if error occurs on undelying Writer
      */
     public static void unescapeJava(Writer out, String str) throws IOException {
         if (out == null) {
@@ -422,6 +424,7 @@ public static String unescapeJavaScript(String str) {
      * @param out  the <code>Writer</code> used to output unescaped characters
      * @param str  the <code>String</code> to unescape, may be null
      * @throws IllegalArgumentException if the Writer is <code>null</code>
+     * @throws IOException if error occurs on undelying Writer
      */
     public static void unescapeJavaScript(Writer out, String str) throws IOException {
         unescapeJava(out, str);

src/java/org/apache/commons/lang/enum/package.html

@@ -30,5 +30,6 @@
     }
 }
 </pre>
+@since 1.0
 </body>
 </html>

src/java/org/apache/commons/lang/exception/ExceptionUtils.java

@@ -78,8 +78,9 @@
  * @author Dmitri Plotnikov
  * @author Stephen Colebourne
  * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
+ * @author Pete Gieser
  * @since 1.0
- * @version $Id: ExceptionUtils.java,v 1.31 2003/07/31 23:45:28 scolebourne Exp $
+ * @version $Id: ExceptionUtils.java,v 1.32 2003/08/16 11:15:20 scolebourne Exp $
  */
 public class ExceptionUtils {
     
@@ -180,9 +181,9 @@ public static Throwable getCause(Throwable throwable) {
      * <p>Introspects the <code>Throwable</code> to obtain the cause.</p>
      * 
      * <ol>
-     * <li>Try known exception types.</p>
-     * <li>Try the supplied array of method names.</p>
-     * <li>Try the field 'detail'.</p>
+     * <li>Try known exception types.</li>
+     * <li>Try the supplied array of method names.</li>
+     * <li>Try the field 'detail'.</li>
      * </ol>
      * 
      * <p>A <code>null</code> set of method names means use the default set.

src/java/org/apache/commons/lang/exception/Nestable.java

@@ -64,14 +64,17 @@
  * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
  * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
  * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
+ * @author Pete Gieser
  * @since 1.0
- * @version $Id: Nestable.java,v 1.7 2003/07/26 13:00:36 scolebourne Exp $
+ * @version $Id: Nestable.java,v 1.8 2003/08/16 11:15:20 scolebourne Exp $
  */
 public interface Nestable {
     
     /**
      * Returns the reference to the exception or error that caused the
      * exception implementing the <code>Nestable</code> to be thrown.
+     *
+     * @return throwable that caused the original exception
      */
     public Throwable getCause();
 

src/java/org/apache/commons/lang/exception/package.html

@@ -6,5 +6,6 @@
 Exception which can handle JDK 1.4 Exceptions as well as others. </p>
 <p>Lastly, {@link org.apache.commons.lang.exception.ExceptionUtils} 
 also contains <code>Throwable</code> manipulation and examination routines.</p>
+@since 1.0
 </body>
 </html>

src/java/org/apache/commons/lang/math/Fraction.java

@@ -65,29 +65,62 @@
  * @author Travis Reeder
  * @author Stephen Colebourne
  * @author Tim O'Brien
+ * @author Pete Gieser
  * @since 2.0
- * @version $Id: Fraction.java,v 1.9 2003/08/13 23:42:17 scolebourne Exp $
+ * @version $Id: Fraction.java,v 1.10 2003/08/16 11:14:01 scolebourne Exp $
  */
 public final class Fraction extends Number implements Serializable, Comparable {
 
     /** Serialization lock, Lang version 2.0 */
     private static final long serialVersionUID = 65382027393090L;
 
+    /**
+     * <code>Fraction</code> representation of 0.
+     */
     public static final Fraction ZERO = new Fraction(0, 1);
+    /**
+     * <code>Fraction</code> representation of 1.
+     */
     public static final Fraction ONE = new Fraction(1, 1);
-
+    /**
+     * <code>Fraction</code> representation of 1/2.
+     */
     public static final Fraction ONE_HALF = new Fraction(1, 2);
-
+    /**
+     * <code>Fraction</code> representation of 1/3.
+     */
     public static final Fraction ONE_THIRD = new Fraction(1, 3);
+    /**
+     * <code>Fraction</code> representation of 2/3.
+     */
     public static final Fraction TWO_THIRDS = new Fraction(2, 3);
-
+    /**
+     * <code>Fraction</code> representation of 1/4.
+     */
     public static final Fraction ONE_QUARTER = new Fraction(1, 4);
+    /**
+     * <code>Fraction</code> representation of 2/4.
+     */
     public static final Fraction TWO_QUARTERS = new Fraction(2, 4);
+    /**
+     * <code>Fraction</code> representation of 3/4.
+     */
     public static final Fraction THREE_QUARTERS = new Fraction(3, 4);
-
+    /**
+     * <code>Fraction</code> representation of 1/5.
+     */
     public static final Fraction ONE_FIFTH = new Fraction(1, 5);
+    /**
+     * <code>Fraction</code> representation of 2/5.
+     */
     public static final Fraction TWO_FIFTHS = new Fraction(2, 5);
+    /**
+     * <code>Fraction</code> representation of 3/5.
+     */
     public static final Fraction THREE_FIFTHS = new Fraction(3, 5);
+    /**
+     * <code>Fraction</code> representation of 4/5.
+     */
     public static final Fraction FOUR_FIFTHS = new Fraction(4, 5);
 
 

src/java/org/apache/commons/lang/math/package.html

@@ -2,5 +2,6 @@
 <body>
 Extends <code>java.math</code> for business mathematical classes. This package is intended for business
 mathematical classes, not scientific ones.
+@since 2.0
 </body>
 </html>

src/java/org/apache/commons/lang/package.html

@@ -2,5 +2,6 @@
 <body>
 Provides highly reusable static utility methods, chiefly concerned 
 with adding value to <code>java.lang</code> and other standard core classes.
+@since 1.0
 </body>
 </html>

src/java/org/apache/commons/lang/reflect/MethodUtils.java

@@ -71,15 +71,18 @@
  * @author Based on code from <code>BeanUtils</code> by: Craig R. McClanahan
  * @author Ralph Schaer
  * @author Chris Audley
- * @author Rey François
- * @author Gregor Raýman
+ * @author Rey Fran<EFBFBD>ois
+ * @author Gregor Ra<EFBFBD>man
  * @author Jan Sorensen
  * @author Robert Burrell Donkin
  * @author Gary Gregory
- * @version $Id: MethodUtils.java,v 1.13 2003/07/20 01:13:54 ggregory Exp $
+ * @version $Id: MethodUtils.java,v 1.14 2003/08/16 11:10:23 scolebourne Exp $
  */
 public class MethodUtils {
 
+    /**
+     * Debug flag.
+     */
     public static final boolean debug = false;
     
     /**
@@ -120,6 +123,7 @@ public static Method getMethod(Class cls, String methodName) {
      *
      * @param cls  the class to reflect, must not be <code>null</code>
      * @param methodName  the field name to obtain
+     * @param paramType  the class of the parameter
      * @return the Method object
      * @throws IllegalArgumentException if the class or method name
      *  is <code>null</code>
@@ -131,11 +135,13 @@ public static Method getMethod(Class cls, String methodName, Class paramType) {
     }
     
     /**
-     * <p>Gets a <code>Method</code> by name.</p> The method must be public.
-     * Superclasses will be considered.</p>
+     * <p>Gets a <code>Method</code> by name.</p>
+     *
+     * <p>The method must be public.  Superclasses will be considered.</p>
      *
      * @param cls  the class to reflect, must not be <code>null</code>
      * @param methodName  the field name to obtain
+     * @param paramTypes  the classes of the parameters
      * @return the Method object
      * @throws IllegalArgumentException if the class or method name
      *  is <code>null</code>
@@ -150,6 +156,7 @@ public static Method getMethod(Class cls, String methodName, Class[] paramTypes)
      *
      * @param cls  the class to reflect, must not be <code>null</code>
      * @param methodName  the method name to obtain
+     * @param paramTypes  the classes of the parameters
      * @param breakScope  whether to break scope restrictions using the
      *  <code>setAccessible</code> method. <code>False</code> will only
      *  match public fields.
@@ -226,6 +233,7 @@ public static Method getMethod(Class cls, String methodName, Class[] paramTypes,
      * no such method can be found, return <code>null</code>.</p>
      *
      * @param method The method that we wish to call
+     * @return Method
      */
     public static Method getMethod(Method method) {
         
@@ -282,6 +290,7 @@ public static Method getMethod(Method method) {
      * @param methodName  get method with this name, must not
      *  be <code>null</code>
      * @param arg  use this argument, must not be <code>null</code>
+     * @return Object
      * @throws ReflectionException if an error occurs during reflection
      * @throws IllegalArgumentException if any parameter is
      *  <code>null</code>
@@ -323,6 +332,7 @@ public static Object invokeMethod(
      *  be <code>null</code>
      * @param args  use these arguments - treat <code>null</code>
      *  as empty array
+     * @return Object
      * @throws ReflectionException if an error occurs during reflection
      * @throws IllegalArgumentException if the objectToInvoke, methodName
      *  or any argument is <code>null</code>
@@ -368,6 +378,7 @@ public static Object invokeMethod(
      * @param args  use these arguments - treat null as empty array
      * @param parameterTypes  match these parameters - treat
      *  <code>null</code> as empty array
+     * @return Object
      * @throws ReflectionException if an error occurs during reflection
      */
     public static Object invokeMethod(

src/java/org/apache/commons/lang/reflect/package.html

@@ -21,4 +21,6 @@ <h4>Java 1.3 And Below</h4>
 The reflection implementation is slow and buggy. 
 If you are using one of these easier java versions, then you will probably find our code
 more reliable than the standard java implementation.</p>
+@since 3.0
 </body>
+</html>

src/java/org/apache/commons/lang/time/DateUtils.java

@@ -74,7 +74,7 @@
  * @author Janek Bogucki
  * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
  * @since 2.0
- * @version $Id: DateUtils.java,v 1.12 2003/08/15 16:14:35 bayard Exp $
+ * @version $Id: DateUtils.java,v 1.13 2003/08/16 11:09:26 scolebourne Exp $
  */
 public class DateUtils {
     
@@ -154,7 +154,7 @@ public class DateUtils {
     public final static int RANGE_MONTH_MONDAY = 6;
 
     /**
-     * <p><code>DateUtils<code> instances should NOT be constructed in
+     * <p><code>DateUtils</code> instances should NOT be constructed in
      * standard programming. Instead, the class should be used as
      * <code>DateUtils.parse(str);</code>.</p>
      *

src/java/org/apache/commons/lang/time/package.html

@@ -10,5 +10,6 @@
 <li><code>DateFormatUtils</code> - a formatting class for dates
 <li><code>StopWatch</code> - a duration timer
 </ul>
+@since 2.0
 </body>
 </html>

src/java/org/apache/commons/lang/util/BitField.java

@@ -56,14 +56,14 @@
 /**
  * <p>Manage operations dealing with bit-mapped fields.</p>
  *
- * <p>Code originated from the POI project.</p>
- *
+ * @author Apache Jakarta POI
  * @author Scott Sanders (sanders at apache dot org)
  * @author Marc Johnson (mjohnson at apache dot org)
  * @author Andrew C. Oliver (acoliver at apache dot org)
  * @author Stephen Colebourne
+ * @author Pete Gieser
  * @since 2.0
- * @version $Id: BitField.java,v 1.6 2003/07/14 22:25:06 bayard Exp $
+ * @version $Id: BitField.java,v 1.7 2003/08/16 11:08:49 scolebourne Exp $
  */
 public class BitField {
     
@@ -100,6 +100,7 @@ public BitField(final int mask) {
      * value is stored as a BitField (and so shifted left so many
      * bits).</p>
      *
+     * @see #setValue
      * @param holder the int data containing the bits we're interested
      *  in
      * @return the selected bits, shifted right appropriately
@@ -117,6 +118,7 @@ public int getValue(final int holder) {
      * value is stored as a BitField (and so shifted left so many
      * bits).</p>
      *
+     * @see #setShortValue
      * @param holder the short data containing the bits we're
      *  interested in
      * @return the selected bits, shifted right appropriately
@@ -183,6 +185,7 @@ public boolean isAllSet(final int holder) {
     /**
      * <p>Replace the bits with new values.</p>
      *
+     * @see #getValue
      * @param holder the int data containint the bits we're
      *  interested in
      * @param value the new value for the specified bits
@@ -196,6 +199,7 @@ public int setValue(final int holder, final int value) {
     /**
      * <p>Replace the bits with new values.</p>
      *
+     * @see #getShortValue
      * @param holder the short data containing the bits we're
      *  interested in
      * @param value the new value for the specified bits

src/java/org/apache/commons/lang/util/package.html

@@ -9,5 +9,6 @@
 <li><code>IdentifierUtils</code> - for creating identifiers
 <li><code>Validate</code> - for validating values and throwing exceptions
 </ul>
+@since 2.0
 </body>
 </html>