From bbab0a4b4c06ce798c163c72e493e16092f443a2 Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Mon, 26 Oct 2009 22:06:13 +0000
Subject: [PATCH] Enhance Javadoc

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@829993 13f79535-47bb-0310-9956-ffa450edef68
---
 .../commons/lang/builder/ToStringBuilder.java | 51 ++++++++-----------
 1 file changed, 22 insertions(+), 29 deletions(-)

diff --git a/src/java/org/apache/commons/lang/builder/ToStringBuilder.java b/src/java/org/apache/commons/lang/builder/ToStringBuilder.java
index b55e1fd9a..f67adfd0b 100644
--- a/src/java/org/apache/commons/lang/builder/ToStringBuilder.java
+++ b/src/java/org/apache/commons/lang/builder/ToStringBuilder.java
@@ -92,7 +92,7 @@
 public class ToStringBuilder {
 
     /**
-     * The default style of output to use.
+     * The default style of output to use, not null.
      */
     private static volatile ToStringStyle defaultStyle = ToStringStyle.DEFAULT_STYLE;
 
@@ -139,7 +139,8 @@ public static void setDefaultStyle(ToStringStyle style) {
 
     //----------------------------------------------------------------------------
     /**
-     * <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
+     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
+     * <code>toString</code> for the specified object.</p>
      * 
      * @param object  the Object to be output
      * @return the String result
@@ -150,7 +151,8 @@ public static String reflectionToString(Object object) {
     }
 
     /**
-     * <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
+     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
+     * <code>toString</code> for the specified object.</p>
      * 
      * @param object  the Object to be output
      * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
@@ -162,7 +164,8 @@ public static String reflectionToString(Object object, ToStringStyle style) {
     }
 
     /**
-     * <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
+     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
+     * <code>toString</code> for the specified object.</p>
      * 
      * @param object  the Object to be output
      * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
@@ -175,7 +178,8 @@ public static String reflectionToString(Object object, ToStringStyle style, bool
     }
 
     /**
-     * <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
+     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
+     * <code>toString</code> for the specified object.</p>
      * 
      * @param object  the Object to be output
      * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
@@ -196,62 +200,51 @@ public static <T> String reflectionToString(
     //----------------------------------------------------------------------------
 
     /**
-     * Current toString buffer.
+     * Current toString buffer, not null.
      */
     private final StringBuffer buffer;
-
     /**
-     * The object being output.
+     * The object being output, may be null.
      */
     private final Object object;
-
     /**
-     * The style of output to use.
+     * The style of output to use, not null.
      */
     private final ToStringStyle style;
 
     /**
-     * <p>Constructor for <code>ToStringBuilder</code>.</p>
+     * <p>Constructs a builder for the specified object using the default output style.</p>
      *
-     * <p>This constructor outputs using the default style set with
-     * <code>setDefaultStyle</code>.</p>
+     * <p>This default style is obtained from {@link #getDefaultStyle()}.</p>
      * 
-     * @param object  the Object to build a <code>toString</code> for
-     * @throws IllegalArgumentException  if the Object passed in is
-     *  <code>null</code>
+     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
      */
     public ToStringBuilder(Object object) {
         this(object, null, null);
     }
 
     /**
-     * <p>Constructor for <code>ToStringBuilder</code> specifying the
-     * output style.</p>
+     * <p>Constructs a builder for the specified object using the a defined output style.</p>
      *
      * <p>If the style is <code>null</code>, the default style is used.</p>
      * 
-     * @param object  the Object to build a <code>toString</code> for
-     * @param style  the style of the <code>toString</code> to create,
-     *  may be <code>null</code>
-     * @throws IllegalArgumentException  if the Object passed in is
-     *  <code>null</code>
+     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
+     * @param style  the style of the <code>toString</code> to create, null uses the default style
      */
     public ToStringBuilder(Object object, ToStringStyle style) {
         this(object, style, null);
     }
 
     /**
-     * <p>Constructor for <code>ToStringBuilder</code>.</p>
+     * <p>Constructs a builder for the specified object.</p>
      *
      * <p>If the style is <code>null</code>, the default style is used.</p>
      *
      * <p>If the buffer is <code>null</code>, a new one is created.</p>
      * 
-     * @param object  the Object to build a <code>toString</code> for
-     * @param style  the style of the <code>toString</code> to create,
-     *  may be <code>null</code>
-     * @param buffer  the <code>StringBuffer</code> to populate, may be
-     *  <code>null</code>
+     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
+     * @param style  the style of the <code>toString</code> to create, null uses the default style
+     * @param buffer  the <code>StringBuffer</code> to populate, may be null
      */
     public ToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer) {
         if (style == null) {