add doc for Node.append

sdk/lib/html/dart2js/html_dart2js.dart

 /// The Dart HTML library.
 library dart.dom.html;
 
 import 'dart:async';
 import 'dart:collection';
 import 'dart:_collection-dev' hide Symbol;
 import 'dart:html_common';
 import 'dart:indexed_db';
 import 'dart:isolate';
 import 'dart:json' as json;
@@ skipping 15271 matching lines @@
   @DomName('Node.textContent')
   @DocsEditable
   String text;
 
   @JSName('addEventListener')
   @DomName('Node.addEventListener')
   @DocsEditable
   void $dom_addEventListener(String type, EventListener listener, [bool useCapture]) native;
 
   @JSName('appendChild')
+  /**
+   * Adds a node to the end of the child [nodes] list of this node.
+   *
+   * If the node already exists in this document, it will be removed from its
+   * current parent node, then added to this node.
+   *
+   * This method is more efficient than `nodes.add`, and is the preferred
+   * way of appending a child node.
+   */
   @DomName('Node.appendChild')
   @DocsEditable
   Node append(Node newChild) native;
 
   @JSName('cloneNode')
   @DomName('Node.cloneNode')
   @DocsEditable
   Node clone(bool deep) native;
 
   @DomName('Node.contains')
@@ skipping 12666 matching lines @@
       _position = nextPosition;
       return true;
     }
     _current = null;
     _position = _array.length;
     return false;
   }
 
   T get current => _current;
 }