Document null behaviour

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

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

@@ -59,10 +59,14 @@
  * <p><code>BooleanUtils</code> contains utility methods for working for
  * boolean and Boolean objects.</p>
  *
+ * <p>This class tries to handle <code>null</code> input gracefully.
+ * An exception will not be thrown for a <code>null</code> input.
+ * Each method documents its behaviour in more detail.</p>
+ * 
  * @author Stephen Colebourne
  * @author Matthew Hawthorne
  * @since 2.0
- * @version $Id: BooleanUtils.java,v 1.7 2003/07/14 22:25:02 bayard Exp $
+ * @version $Id: BooleanUtils.java,v 1.8 2003/07/19 20:17:12 scolebourne Exp $
  */
 public class BooleanUtils {
 
@@ -84,7 +88,7 @@ public BooleanUtils() {
      * <p>If <code>null</code> is passed in, <code>null</code> will be returned.</p>
      * 
      * @param bool  the Boolean to negate, may be null
-     * @return the negated Boolean, or <code>null</code> if <code>null</code> passed in
+     * @return the negated Boolean, or <code>null</code> if <code>null</code> input
      */
     public static Boolean negate(Boolean bool) {
         if (bool == null) {
@@ -112,7 +116,8 @@ public static Boolean toBooleanObject(boolean bool) {
      * by returning <code>false</code>.</p>
      * 
      * @param bool  the boolean to convert
-     * @return <code>true</code> or <code>false</code>
+     * @return <code>true</code> or <code>false</code>, 
+     *  <code>null</code> returns <code>false</code>
      */
     public static boolean toBoolean(Boolean bool) {
         if (bool == null) {
@@ -169,7 +174,7 @@ public static Boolean toBooleanObject(int value) {
      * 
      * @param value  the Integer to convert
      * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
-     *  <code>null</code> if <code>null</code>
+     *  <code>null</code> if <code>null</code> input
      */
     public static Boolean toBooleanObject(Integer value) {
         if (value == null) {
@@ -392,8 +397,8 @@ public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer f
      * Otherwise, <code>null</code> is returned.</p>
      *
      * @param str  the String to check
-     * @return the Boolean value of the string, <code>null</code>
-     *  if no match or <code>null</code> input
+     * @return the Boolean value of the string,
+     *  <code>null</code> if no match or <code>null</code> input
      */
     public static Boolean toBooleanObject(String str) {
         if ("true".equalsIgnoreCase(str)) {
@@ -423,8 +428,8 @@ public static Boolean toBooleanObject(String str) {
      *  (case sensitive), may be <code>null</code>
      * @param nullString  the String to match for <code>null</code>
      *  (case sensitive), may be <code>null</code>
-     * @return the Boolean value of the string, <code>null</code>
-     *  if no match or <code>null</code> input
+     * @return the Boolean value of the string,
+     *  <code>null</code> if no match or <code>null</code> input
      */
     public static Boolean toBooleanObject(String str, String trueString, String falseString, String nullString) {
         if (str == null) {

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

@@ -59,10 +59,13 @@
 /**
  * <p>Provides utility methods for working for classes without using reflection.</p>
  *
+ * <p>This class throws exceptions for invalid <code>null</code> inputs.
+ * Each method documents its behaviour in more detail.</p>
+ *
  * @author Stephen Colebourne
  * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
  * @since 2.0
- * @version $Id: ClassUtils.java,v 1.15 2003/07/16 21:19:22 scolebourne Exp $
+ * @version $Id: ClassUtils.java,v 1.16 2003/07/19 20:17:12 scolebourne Exp $
  */
 public class ClassUtils {
 

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

@@ -54,8 +54,13 @@
 package org.apache.commons.lang;
 
 import java.io.Serializable;
+
 /**
  * <p>Common <code>Object</code> manipulation routines.</p>
+ * 
+ * <p>This class tries to handle <code>null</code> input gracefully.
+ * An exception will generally not be thrown for a <code>null</code> input.
+ * Each method documents its behaviour in more detail.</p>
  *
  * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
  * @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
@@ -63,7 +68,7 @@
  * @author Stephen Colebourne
  * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
  * @since 1.0
- * @version $Id: ObjectUtils.java,v 1.11 2003/07/16 01:47:39 ggregory Exp $
+ * @version $Id: ObjectUtils.java,v 1.12 2003/07/19 20:21:39 scolebourne Exp $
  */
 public class ObjectUtils {
     
@@ -130,7 +135,7 @@ public static boolean equals(Object object1, Object object2) {
     
     /**
      * <p>Gets the toString that would be produced by <code>Object</code>
-     * if a class did not override toString itself. <code>Null</code>
+     * if a class did not override toString itself. <code>null</code>
      * will return <code>null</code>.</p>
      *
      * @param object  the object to create a toString for, may be
@@ -147,7 +152,7 @@ public static String identityToString(Object object) {
 
     /**
      * <p>Appends the toString that would be produced by <code>Object</code>
-     * if a class did not override toString itself. <code>Null</code>
+     * if a class did not override toString itself. <code>null</code>
      * will return <code>null</code>.</p>
      *
      * @param buffer  the buffer to append to, may not be