Documenting misleading DataTransfer API.

sdk/lib/html/dart2js/html_dart2js.dart

Index: sdk/lib/html/dart2js/html_dart2js.dart
diff --git a/sdk/lib/html/dart2js/html_dart2js.dart b/sdk/lib/html/dart2js/html_dart2js.dart
index fa018931621c5a3aed08d0e726ea9903aae0da69..df21606bba0cf65ea6301a24b812d1278fa83dbf 100644
--- a/sdk/lib/html/dart2js/html_dart2js.dart
+++ b/sdk/lib/html/dart2js/html_dart2js.dart
@@ -5828,6 +5828,21 @@ 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

[Andrei Mouravski, 2013/02/01 18:40:45]

Nit: There's an extra space between "the" and "data".

+   * onDrop event) and will return `null` before then.

[Andrei Mouravski, 2013/02/01 18:40:45]

Nit: link to onDrop event if you can.

[Andrei Mouravski, 2013/02/01 18:40:45]

"... and will return `null` anywhere else."
or maybe
"... and will return `null` before the event is triggered."

Whichever is more accurate.

[blois, 2013/04/10 00:26:47]

Done.

[blois, 2013/04/10 00:26:47]

Done.

+   *
+   * Data transfer is also prohibited across domains. If a drag originates

[Andrei Mouravski, 2013/02/01 18:40:45]

No need for "also." Just:
"Data transfer is prohibited across domains."

+   * 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;