Merge pull request #2164 from Hixie/remove-back

Remove old 'back' callback, and add dartdocs.

sky/engine/core/dart/hooks.dart

@@ -36,9 +36,6 @@ void _pushRoute(String route) {
 void _popRoute() {
   if (window.onPopRoute != null)
     window.onPopRoute();
-  // TODO(abarth): Remove after engine roll.
-  if (window.onEvent != null)
-    window.onEvent('back', 0.0);
 }
 
 void _dispatchPointerPacket(ByteData serializedPacket) {

sky/engine/core/dart/text.dart

@@ -181,9 +181,9 @@ enum TextDecorationStyle {
 //
 //  - Element 3: The |decorationColor| in ARGB with 8 bits per channel.
 //
-//  - Element 4: The enum index of the |decorationStyle|.
+//  - Element 4: The bit field of the |decorationStyle|.
 //
-//  - Element 5: The enum index of the |fontWeight|.
+//  - Element 5: The index of the |fontWeight|.
 //
 //  - Element 6: The enum index of the |fontStyle|.
 //

sky/engine/core/dart/window.dart

@@ -6,9 +6,14 @@ part of dart_ui;
 
 typedef void VoidCallback();
 typedef void _FrameCallback(Duration duration);
-typedef void _EventCallback(String eventType, double timeStamp);
 typedef void _PointerPacketCallback(ByteData serializedPacket);
 
+/// A representation of distances for each of the four edges of a rectangle,
+/// used to encode the padding that applications should place around their user
+/// interface, as exposed by [Window.padding].
+///
+/// For a generic class that represents distances around a rectangle, see the
+/// [EdgeDims] class.
 class WindowPadding {
   const WindowPadding._({ this.top, this.right, this.bottom, this.left });
 
@@ -18,41 +23,102 @@ class WindowPadding {
   final double left;
 }
 
+/// An identifier used to select a user's language and formatting preferences,
+/// consisting of a language and a country. This is a subset of locale
+/// identifiers as defined by BCP 47.
 class Locale {
-  Locale(this.languageCode, this.countryCode);
+  const Locale(this.languageCode, this.countryCode);
 
+  /// The primary language subtag for the locale.
   final String languageCode;
+
+  /// The region subtag for the locale.
   final String countryCode;
 
+  bool operator ==(dynamic other) {
+    if (identical(this, other))
+      return true;
+    if (other is! Locale)
+      return false;
+    final Locale typedOther = other;
+    return languageCode == typedOther.languageCode
+        && countryCode == typedOther.countryCode;
+  }
+
+  int get hashCode {
+    int result = 373;
+    result = 37 * result + languageCode.hashCode;
+    result = 37 * result + countryCode.hashCode;
+    return result;
+  }
+
   String toString() => '${languageCode}_$countryCode';
 }
 
+/// The most basic interface to the host operating system's user interface.
 class Window {
   Window._();
 
+  /// The number of device pixels for each logical pixel. This number might not
+  /// be a power of two. Indeed, it might not even be an integer. For example,
+  /// the Nexus 6 has a device pixel ratio of 3.5.
   double get devicePixelRatio => _devicePixelRatio;
   double _devicePixelRatio;
 
+  /// The dimensions of the rectangle into which the application will be drawn,
+  /// in logical pixels.
   Size get size => _size;
   Size _size;
 
+  /// The number of pixels on each side of the display rectangle into which the
+  /// application can render, but over which the operating system will likely
+  /// place system UI (such as the Android system notification area).
   WindowPadding get padding => _padding;
   WindowPadding _padding;
 
+  /// A callback that is invoked whenever the [devicePixelRatio], [size], or
+  /// [padding] values change.
+  VoidCallback onMetricsChanged;
+
+  /// The system-reported locale. This establishes the language and formatting
+  /// conventions that application should, if possible, use to render their user
+  /// interface.
   Locale get locale => _locale;
   Locale _locale;
 
+  /// A callback that is invoked whenever [locale] changes value.
+  VoidCallback onLocaleChanged;
+
+  /// A callback that is invoked to notify the application that it is an
+  /// appropriate time to provide a scene using the [SceneBuilder] API and the
+  /// [render()] method. When possible, this is driven by the hardware VSync
+  /// signal. This is only called if [scheduleFrame()] has been called since the
+  /// last time this callback was invoked.
   _FrameCallback onBeginFrame;
-  _EventCallback onEvent; // TODO(abarth): Remove.
+
+  /// A callback that is invoked when pointer data is available. The data is
+  /// provided in the form of a raw byte stream containing an encoded mojo
+  /// PointerPacket.
   _PointerPacketCallback onPointerPacket;
-  VoidCallback onMetricsChanged;
-  VoidCallback onLocaleChanged;
 
+  /// The route or path that the operating system requested when the application
+  /// was launched.
   String defaultRouteName;
+
+  /// A callback that is invoked when the operating system requests that the
+  /// application goes "back" one step in its history. For example, on Android
+  /// this is invoked in response to the "back" button.
   VoidCallback onPopRoute;
 
+  /// Requests that, at the next appropriate opportunity, the [onBeginFrame]
+  /// callback be invoked.
   void scheduleFrame() native "Window_scheduleFrame";
+
+  /// Updates the application's rendering on the GPU with the newly provided
+  /// [Scene]. For optimal performance, this should only be called in response
+  /// to the [onBeginFrame] callback being invoked.
   void render(Scene scene) native "Window_render";
 }
 
+/// The [Window] singleton.
 final Window window = new Window._();