Miscellaneous documentation improvements (#13719)

This is a collection of fixes I've run into recently.

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

@@ -189,7 +189,7 @@ abstract class BindingBase {
     assert(!locked);
   }
 
-  /// Cause the entire application to redraw.
+  /// Cause the entire application to redraw, e.g. after a hot reload.
   ///
   /// This is used by development tools when the application code has changed,
   /// to cause the application to pick up any changed code. It can be triggered
@@ -212,7 +212,7 @@ abstract class BindingBase {
   }
 
   /// This method is called by [reassembleApplication] to actually cause the
-  /// application to reassemble.
+  /// application to reassemble, e.g. after a hot reload.
   ///
   /// Bindings are expected to use this method to reregister anything that uses
   /// closures, so that they do not keep pointing to old code, and to flush any

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

@@ -997,10 +997,14 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
   }
 
   /// Cause the entire subtree rooted at the given [RenderObject] to be marked
-  /// dirty for layout, paint, etc. This is called by the [RendererBinding] in
-  /// response to the `ext.flutter.reassemble` hook, which is used by
-  /// development tools when the application code has changed, to cause the
-  /// widget tree to pick up any changed implementations.
+  /// dirty for layout, paint, etc, so that the effects of a hot reload can be
+  /// seen, or so that the effect of changing a global debug flag (such as
+  /// [debugPaintSizeEnabled]) can be applied.
+  ///
+  /// This is called by the [RendererBinding] in response to the
+  /// `ext.flutter.reassemble` hook, which is used by development tools when the
+  /// application code has changed, to cause the widget tree to pick up any
+  /// changed implementations.
   ///
   /// This is expensive and should not be called except during development.
   ///

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

@@ -244,7 +244,7 @@ abstract class TextInputClient {
   void performAction(TextInputAction action);
 }
 
-/// A interface for interacting with a text input control.
+/// An interface for interacting with a text input control.
 ///
 /// See also:
 ///

packages/flutter/lib/src/widgets/framework.dart

@@ -857,6 +857,10 @@ typedef void StateSetter(VoidCallback fn);
 ///    associated widget (e.g., to start implicit animations). The framework
 ///    always calls [build] after calling [didUpdateWidget], which means any
 ///    calls to [setState] in [didUpdateWidget] are redundant.
+///  * During development, if a hot reload occurs (whether initiated from the
+///    command line `flutter` tool by pressing `r`, or from an IDE), the
+///    [reassemble] method is called. This provides an opportunity to
+///    reinitialize any data that was prepared in the [initState] method.
 ///  * If the subtree containing the [State] object is removed from the tree
 ///    (e.g., because the parent built a widget with a different [runtimeType]
 ///    or [Widget.key]), the framework calls the [deactivate] method. Subclasses
@@ -994,7 +998,8 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   @protected
   void didUpdateWidget(covariant T oldWidget) { }
 
-  /// Called whenever the application is reassembled during debugging.
+  /// Called whenever the application is reassembled during debugging, for
+  /// example during hot reload.
   ///
   /// This method should rerun any initialization logic that depends on global
   /// state, for example, image loading from asset bundles (since the asset
@@ -2001,7 +2006,7 @@ abstract class BuildContext {
 /// This class tracks which widgets need rebuilding, and handles other tasks
 /// that apply to widget trees as a whole, such as managing the inactive element
 /// list for the tree and triggering the "reassemble" command when necessary
-/// during debugging.
+/// during hot reload when debugging.
 ///
 /// The main build owner is typically owned by the [WidgetsBinding], and is
 /// driven from the operating system along with the rest of the
@@ -2365,7 +2370,8 @@ class BuildOwner {
 
   /// Cause the entire subtree rooted at the given [Element] to be entirely
   /// rebuilt. This is used by development tools when the application code has
-  /// changed, to cause the widget tree to pick up any changed implementations.
+  /// changed and is being hot-reloaded, to cause the widget tree to pick up any
+  /// changed implementations.
   ///
   /// This is expensive and should not be called except during development.
   void reassemble(Element root) {

packages/flutter/lib/src/widgets/routes.dart

@@ -1114,7 +1114,6 @@ abstract class PopupRoute<T> extends ModalRoute<T> {
 ///   Widget build(BuildContext context) => new Container();
 ///
 /// }
-///
 /// ```
 class RouteObserver<T extends Route<dynamic>> extends NavigatorObserver {
   final Map<T, RouteAware> _listeners = <T, RouteAware>{};
@@ -1157,7 +1156,10 @@ class RouteObserver<T extends Route<dynamic>> extends NavigatorObserver {
   }
 }
 
-/// A interface that is aware of its current Route.
+/// An interface for objects that are aware of their current [Route].
+///
+/// This is used with [RouteObserver] to make a widget aware of changes to the
+/// [Navigator]'s session history.
 abstract class RouteAware {
   /// Called when the top route has been popped off, and the current route
   /// shows up.

packages/flutter/lib/src/widgets/text_selection.dart

@@ -21,15 +21,23 @@ import 'transitions.dart';
 ///
 /// With mixed-direction text, both handles may be the same type. Examples:
 ///
-/// * LTR text: 'the <quick brown> fox':
-///   The '<' is drawn with the [left] type, the '>' with the [right]
+/// * LTR text: 'the &lt;quick brown&gt; fox':
+///
+///   The '&lt;' is drawn with the [left] type, the '&gt;' with the [right]
+///
+/// * RTL text: 'XOF &lt;NWORB KCIUQ&gt; EHT':
 ///
-/// * RTL text: 'xof <nworb kciuq> eht':
 ///   Same as above.
 ///
-/// * mixed text: '<the nwor<b quick fox'
-///   Here 'the b' is selected, but 'brown' is RTL. Both are drawn with the
-///   [left] type.
+/// * mixed text: '&lt;the NWOR&lt;B KCIUQ fox'
+///
+///   Here 'the QUICK B' is selected, but 'QUICK BROWN' is RTL. Both are drawn
+///   with the [left] type.
+///
+/// See also:
+///
+///  * [TextDirection], which discusses left-to-right and right-to-left text in
+///    more detail.
 enum TextSelectionHandleType {
   /// The selection handle is to the left of the selection end point.
   left,