Documenting misleading DataTransfer API.

BUG=

Review URL: https://codereview.chromium.org//12092114

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@21216 260f80e4-7a28-3924-810f-c04153c831b5

sdk/lib/html/dart2js/html_dart2js.dart

@@ -5546,6 +5546,22 @@ class DataTransfer native "*Clipboard" {
   @DocsEditable
   void clearData([String type]) native;
 
+  /**
+   * Gets the data for the specified type.
+   *
+   * The data is only available from within a drop operation (such as an
+   * [Element.onDrop] event) and will return `null` before the event is
+   * triggered.
+   *
+   * Data transfer is prohibited across domains. If a drag originates
+   * from content from another domain or protocol (HTTP vs HTTPS) then the
+   * data cannot be accessed.
+   *
+   * The [type] can have values such as:
+   *
+   * * `'Text'`
+   * * `'URL'`
+   */
   @DomName('Clipboard.getData')
   @DocsEditable
   String getData(String type) native;

sdk/lib/html/dartium/html_dartium.dart

@@ -6042,6 +6042,22 @@ class DataTransfer extends NativeFieldWrapperClass1 {
   @DocsEditable
   void clearData([String type]) native "Clipboard_clearData_Callback";
 
+  /**
+   * Gets the data for the specified type.
+   *
+   * The data is only available from within a drop operation (such as an
+   * [Element.onDrop] event) and will return `null` before the event is
+   * triggered.
+   *
+   * Data transfer is prohibited across domains. If a drag originates
+   * from content from another domain or protocol (HTTP vs HTTPS) then the
+   * data cannot be accessed.
+   *
+   * The [type] can have values such as:
+   *
+   * * `'Text'`
+   * * `'URL'`
+   */
   @DomName('Clipboard.getData')
   @DocsEditable
   String getData(String type) native "Clipboard_getData_Callback";

tools/dom/docs/docs.json

@@ -92,6 +92,28 @@
         ]
       }
     },
+    "Clipboard": {
+      "members": {
+        "getData": [
+          "/**",
+          "   * Gets the data for the specified type.",
+          "   *",
+          "   * The data is only available from within a drop operation (such as an",
+          "   * [Element.onDrop] event) and will return `null` before the event is",
+          "   * triggered.",
+          "   *",
+          "   * Data transfer is prohibited across domains. If a drag originates",
+          "   * from content from another domain or protocol (HTTP vs HTTPS) then the",
+          "   * data cannot be accessed.",
+          "   *",
+          "   * The [type] can have values such as:",
+          "   *",
+          "   * * `'Text'`",
+          "   * * `'URL'`",
+          "   */"
+        ]
+      }
+    },
     "Document": {
       "members": {
         "body": [