Merge pull request #2753 from Hixie/binding-docs

Add some docs for people looking at bindings

packages/flutter/lib/src/rendering/binding.dart

@@ -118,6 +118,13 @@ void debugDumpSemanticsTree() {
 
 /// A concrete binding for applications that use the Rendering framework
 /// directly. This is the glue that binds the framework to the Flutter engine.
+///
+/// You would only use this binding if you are writing to the
+/// rendering layer directly. If you are writing to a higher-level
+/// library, such as the Flutter Widgets library, then you would use
+/// that layer's binding.
+///
+/// See also [BindingBase].
 class RenderingFlutterBinding extends BindingBase with Scheduler, Gesturer, Services, Renderer {
   RenderingFlutterBinding({ RenderBox root }) {
     assert(renderView != null);

packages/flutter/lib/src/services/binding.dart

@@ -13,6 +13,16 @@ export 'package:flutter/shell.dart';
 /// [initInstances()]. The mixin is guaranteed to only be constructed once in
 /// the lifetime of the app (more precisely, it will assert if constructed twice
 /// in checked mode).
+///
+/// The top-most layer used to write the application will have a
+/// concrete class that inherits from BindingBase and uses all the
+/// various BindingBase mixins (such as [Services]). For example, the
+/// Widgets library in flutter introduces a binding called
+/// [WidgetFlutterBinding]. The relevant library defines how to create
+/// the binding. It could be implied (for example,
+/// [WidgetFlutterBinding] is automatically started from [runApp]), or
+/// the application might be required to explicitly call the
+/// constructor.
 abstract class BindingBase {
   BindingBase() {
     assert(!_debugInitialized);