Fix error in usage of newly-creted helper method in AttachableHTMLPanel, correct double-calling of wrapElement in exceptional case, and fix the documentation.

Review at http://gwt-code-reviews.appspot.com/1427812

Review by: rjrjr@google.com

git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@10140 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/user/src/com/google/gwt/user/client/ui/AttachableHTMLPanel.java b/user/src/com/google/gwt/user/client/ui/AttachableHTMLPanel.java
index 02b5414..590cf06 100644
--- a/user/src/com/google/gwt/user/client/ui/AttachableHTMLPanel.java
+++ b/user/src/com/google/gwt/user/client/ui/AttachableHTMLPanel.java
@@ -202,14 +202,20 @@
 
   @Override
   public void wrapElement(Element element) {
-    if (!isFullyInitialized()) {
-      // NOTE(rdcastro): This code is only run when Attachable is in active use.
-      element.getParentNode().replaceChild(getElement(), element);
-    } else {
-      setElement(element);
-      html = null;
+    if (isFullyInitialized()) {
+      /*
+       * If wrapElement is being called after the widget is fully initialized,
+       * that's probably a programming error, as it's much more efficient to
+       * build the whole tree at once.
+       */
+      throw new IllegalStateException(
+          "wrapElement() cannot be called twice, or after a call to getElement()"
+          + "has forced the widget to render itself (e.g. after adding it to a"
+          + "panel)");
     }
 
+    setElement(element);
+    html = null;
     if (wrapInitializationCallback != null) {
       wrapInitializationCallback.execute();
       wrapInitializationCallback = null;