Add some dartdoc comments

sky/sdk/lib/widgets/widget.dart

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 import 'dart:async';
 import 'dart:collection';
 import 'dart:mirrors';
 import 'dart:sky' as sky;
 
 import 'package:sky/mojo/activity.dart' as activity;
 
 import '../base/hit_test.dart';
 import '../rendering/box.dart';
 import '../rendering/object.dart';
 import '../rendering/sky_binding.dart';
 
 export '../rendering/box.dart' show BoxConstraints, BoxDecoration, Border, BorderSide, EdgeDims;
 export '../rendering/flex.dart' show FlexDirection;
 export '../rendering/object.dart' show Point, Offset, Size, Rect, Color, Paint, Path;
 
 final bool _shouldLogRenderDuration = false;
 
 typedef void WidgetTreeWalker(Widget);
 
-// All Effen nodes derive from Widget. All nodes have a _parent, a _key and
-// can be sync'd.
+/// A base class for elements of the widget tree
 abstract class Widget {
 
   Widget({ String key }) : _key = key {
     assert(_isConstructedDuringBuild());
   }
 
   // TODO(jackson): Remove this workaround for limitation of Dart mixins
   Widget._withKey(String key) : _key = key {
     assert(_isConstructedDuringBuild());
   }
 
   // you should not build the UI tree ahead of time, build it only during build()
   bool _isConstructedDuringBuild() => this is AbstractWidgetRoot || this is App || _inRenderDirtyComponents;
 
   String _key;
+
+  /// A semantic identifer for this widget
+  ///
+  /// Keys are used to find matches when synchronizing two widget trees, for
+  /// example after a [Component] rebuilds. Without keys, two widgets can match
+  /// if their runtimeType matches. With keys, the keys must match as well.
+  /// Assigning a key to a widget can improve performance by causing the
+  /// framework to sync widgets that share a lot of common structure and can
+  /// help match stateful components semantically rather than positionally.
   String get key => _key;
 
   Widget _parent;
+
+  /// The parent of this widget in the widget tree.
   Widget get parent => _parent;
 
   bool _mounted = false;
   bool _wasMounted = false;
   bool get mounted => _mounted;
   static bool _notifyingMountStatus = false;
   static List<Widget> _mountedChanged = new List<Widget>();
 
+  /// Called during the synchronizing process to update the widget's parent.
   void setParent(Widget newParent) {
     assert(!_notifyingMountStatus);
     if (_parent == newParent)
       return;
     _parent = newParent;
     if (newParent == null) {
       if (_mounted) {
         _mounted = false;
         _mountedChanged.add(this);
       }
     } else {
       assert(newParent._mounted);
       if (_parent._mounted != _mounted) {
         _mounted = _parent._mounted;
         _mountedChanged.add(this);
       }
     }
   }
 
-  // Override this if you have children and call walker on each child.
-  // Note that you may be called before the child has had its parent
-  // pointer set to point to you. Your walker, and any methods it
-  // invokes on your descendants, should not rely on the ancestor
-  // chain being correctly configured at this point.
+  /// Walks the immediate children of this widget
+  ///
+  /// Override this if you have children and call walker on each child.
+  /// Note that you may be called before the child has had its parent
+  /// pointer set to point to you. Your walker, and any methods it
+  /// invokes on your descendants, should not rely on the ancestor
+  /// chain being correctly configured at this point.
   void walkChildren(WidgetTreeWalker walker) { }
 
   static void _notifyMountStatusChanged() {
     try {
       sky.tracing.begin("Widget._notifyMountStatusChanged");
       _notifyingMountStatus = true;
       for (Widget node in _mountedChanged) {
         if (node._wasMounted != node._mounted) {
           if (node._mounted)
             node.didMount();
           else
             node.didUnmount();
           node._wasMounted = node._mounted;
         }
       }
       _mountedChanged.clear();
     } finally {
       _notifyingMountStatus = false;
       sky.tracing.end("Widget._notifyMountStatusChanged");
     }
   }
+
+  /// Override this function to learn when this [Widget] enters the widget tree.
   void didMount() { }
+
+  /// Override this function to learn when this [Widget] leaves the widget tree.
   void didUnmount() { }
 
   RenderObject _root;
+
+  /// The underlying [RenderObject] associated with this [Widget].
   RenderObject get root => _root;
 
   // Subclasses which implements Nodes that become stateful may return true
   // if the |old| node has become stateful and should be retained.
   // This is called immediately before _sync().
   // Component._retainStatefulNodeIfPossible() calls syncFields().
   bool _retainStatefulNodeIfPossible(Widget old) => false;
 
   void _sync(Widget old, dynamic slot);
   void updateSlot(dynamic newSlot);
@@ skipping 978 matching lines @@
     if (root.parent == null) {
       // we haven't attached it yet
       assert(_container.child == null);
       _container.child = root;
     }
     assert(root.parent == _container);
   }
 
   Widget build() => builder();
 }