Refines the HasValue documentation, in particular wrt use of null and value equality. Desk review by jlabanca git-svn-id: https://google-web-toolkit.googlecode.com/svn/releases/1.6@4164 8db76d5a-ed1c-0410-87a9-c151d255dfc7

diff --git a/user/src/com/google/gwt/user/client/ui/CheckBox.java b/user/src/com/google/gwt/user/client/ui/CheckBox.java
index 1b1a8f3..a9eba4f 100644
--- a/user/src/com/google/gwt/user/client/ui/CheckBox.java
+++ b/user/src/com/google/gwt/user/client/ui/CheckBox.java

@@ -219,6 +219,7 @@
   }
 
   public void setValue(Boolean value, boolean fireEvents) {
+    assert null != value : "Value must not be null";
     if (isChecked() == value) {
       return;
     }

diff --git a/user/src/com/google/gwt/user/client/ui/HasValue.java b/user/src/com/google/gwt/user/client/ui/HasValue.java
index f3240e9..0c7d36f 100644
--- a/user/src/com/google/gwt/user/client/ui/HasValue.java
+++ b/user/src/com/google/gwt/user/client/ui/HasValue.java

@@ -20,6 +20,11 @@
 /**
  * An object that implements this interface should be a user input widget, where
  * the user and programmer can both set and get the object's value.
+ * <p>
+ * It is a requirement that a value passed to {@link setValue} be
+ * {@link Object#equals} to that returned by an immediately succeeding call to
+ * {@link getValue}, or that both be null. Note that this is not a requirement
+ * that <code>setValue(null)</code> be supported by all implementors.
  * 
  * @param <T> the type of value.
  */
@@ -33,8 +38,11 @@
   T getValue();
 
   /**
-   * Sets this object's value without firing any events. Should call setValue(T
-   * value, false).
+   * Sets this object's value without firing any events. This should be
+   * identical to calling setValue(value, false).
+   * <p>
+   * It is acceptable to fail assertions or throw (documented) unchecked
+   * exceptions in response to bad values.
    * 
    * @param value the object's new value
    */
@@ -44,6 +52,9 @@
    * Sets this object's value. Fires
    * {@link com.google.gwt.event.logical.shared.ValueChangeEvent} when
    * fireEvents is true and the new value does not equal the existing value.
+   * <p>
+   * It is acceptable to fail assertions or throw (documented) unchecked
+   * exceptions in response to bad values.
    * 
    * @param value the object's new value
    * @param fireEvents fire events if true and value is new

diff --git a/user/src/com/google/gwt/user/client/ui/TextBoxBase.java b/user/src/com/google/gwt/user/client/ui/TextBoxBase.java
index 3a8554e..3f7660a 100644
--- a/user/src/com/google/gwt/user/client/ui/TextBoxBase.java
+++ b/user/src/com/google/gwt/user/client/ui/TextBoxBase.java

@@ -301,6 +301,7 @@
   }
 
   public void setValue(String value, boolean fireEvents) {
+    assert null != value : "Value must not be null";
     String oldValue = getText();
     setText(value);
     if (fireEvents) {