Docs improvements per @Hixie's comments (flutter/engine#7387)

engine/src/flutter/lib/ui/text.dart

@@ -882,43 +882,47 @@ class TextBox {
 /// characters. For newline characters, the position is fully specified by the
 /// offset alone, and there is no ambiguity.
 ///
-/// TextAffinity also affects bidirectional text at the interface between LTR
+/// [TextAffinity] also affects bidirectional text at the interface between LTR
 /// and RTL text. Consider the following string, where the lowercase letters
 /// will be displayed as LTR and the uppercase letters RTL: "helloHELLO".  When
 /// rendered, the string would appear visually as "helloOLLEH".  An offset of 5
-/// would be ambiguous without a corresponding TextAffinity.  Looking at the
+/// would be ambiguous without a corresponding [TextAffinity].  Looking at the
 /// string in code, the offset represents the position just after the "o" and
 /// just before the "H".  When rendered, this offset could be either in the
 /// middle of the string to the right of the "o" or at the end of the string to
 /// the right of the "H".
 enum TextAffinity {
-  /// The position has affinity for the upstream side of the text position, or
+  /// The position has affinity for the upstream side of the text position, i.e.
   /// in the direction of the beginning of the string.
   ///
   /// In the example of an offset at the place where text is wrapping, upstream
   /// indicates the end of the first line.
   ///
-  /// In the bidirectional text example above, an offset of 5 with TextAffinity
-  /// upstream would appear in the middle of the rendered text, just to the
-  /// right of the "o".
+  /// In the bidirectional text example "helloHELLO", an offset of 5 with
+  /// [TextAffinity] upstream would appear in the middle of the rendered text,
+  /// just to the right of the "o". See the definition of [TextAffinity] for the
+  /// full example.
   upstream,
 
-  /// The position has affinity for the downstream side of the text position, or
-  /// in the direction of the end of the string.
+  /// The position has affinity for the downstream side of the text position,
+  /// i.e. in the direction of the end of the string.
   ///
   /// In the example of an offset at the place where text is wrapping,
   /// downstream indicates the beginning of the second line.
   ///
-  /// In the bidirectional text example above, an offset of 5 with TextAffinity
-  /// downstream would appear at the end of the rendered text, just to the right
-  /// of the "H".
+  /// In the bidirectional text example "helloHELLO", an offset of 5 with
+  /// [TextAffinity] downstream would appear at the end of the rendered text,
+  /// just to the right of the "H". See the definition of [TextAffinity] for the
+  /// full example.
   downstream,
 }
 
-/// A position in a string of text. A TextPosition can be used to locate a
-/// position in a string in code (using the [offset] property), and it can also
-/// be used to locate the same position visually in a rendered string of text
-/// (using [offset] and, when needed to resolve ambiguity, [affinity]).
+/// A position in a string of text.
+///
+/// A TextPosition can be used to locate a position in a string in code (using
+/// the [offset] property), and it can also be used to locate the same position
+/// visually in a rendered string of text (using [offset] and, when needed to
+/// resolve ambiguity, [affinity]).
 ///
 /// The location of an offset in a rendered string is ambiguous in two cases.
 /// One happens when rendered text is forced to wrap. In this case, the offset