Various doc fixes (#35548)

dev/snippets/config/templates/README.md

@@ -68,33 +68,35 @@ follows:
 
 - [`stateful_widget`](stateful_widget.tmpl) :
   The default code block will be placed as the body of the `State` object of a
-  StatefulWidget subclass. Because the default code block is placed as the body
-  of a stateful widget, you will need to implement the `build()` function, and any
+  `StatefulWidget` subclass. Because the default code block is placed as the body
+  of a stateful widget, you will need to implement the `build()` method, and any
   state variables. It also has a `preamble` in addition to the default code
   block, which will be placed at the top level of the Dart file, so bare
-  function calls are not allowed in the preamble.  It also has an `imports`
+  method calls are not allowed in the preamble. The default code block is
+  placed as the body of a stateful widget, so you will need to implement the
+  `build()` method, and any state variables. It also has an `imports`
   section to import additional packages. Please only import things that are part
   of flutter or part of default dependencies for a `flutter create` project.
-  It creates a WidgetsApp around the child stateful widget.
+  It creates a `WidgetsApp` around the child stateful widget.
 
-- [`stateless_widget`](stateless_widget.tmpl) :
-  Identical to the `stateful_widget` template, except that the default code
-  block is inserted as the `build` function in a
-  StatelessWidget. There is no need to include the @override before the build
-  function (the template adds this for you).
+- [`stateless_widget`](stateless_widget.tmpl) : Identical to the
+  `stateful_widget` template, except that the default code block is
+  inserted as a method (which should be the `build` method) in a
+  `StatelessWidget`. The `@override` before the build method is added by
+  the template, so must be omitted from the sample code.
 
 - [`stateful_widget_material`](stateful_widget_material.tmpl) : Similar to
   `stateful_widget`, except that it imports the material library, and uses
-  a MaterialApp instead of WidgetsApp.
+  a `MaterialApp` instead of `WidgetsApp`.
 
 - [`stateless_widget_material`](stateless_widget_material.tmpl) : Similar to
   `stateless_widget`, except that it imports the material library, and uses
-  a MaterialApp instead of WidgetsApp.
+  a `MaterialApp` instead of `WidgetsApp`.
 
 - [`stateful_widget_scaffold`](stateful_widget_scaffold.tmpl) : Similar to
   `stateful_widget_material`, except that it wraps the stateful widget with a
-  Scaffold.
+  `Scaffold`.
 
 - [`stateless_widget_scaffold`](stateless_widget_scaffold.tmpl) : Similar to
   `stateless_widget_material`, except that it wraps the stateless widget with a
-  Scaffold.
+  `Scaffold`.

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

@@ -3017,11 +3017,11 @@ mixin ContainerRenderObjectMixin<ChildType extends RenderObject, ParentDataType
     _childCount = 0;
   }
 
-  /// Move this child in the child list to be before the given child.
+  /// Move the given `child` in the child list to be after another child.
   ///
   /// More efficient than removing and re-adding the child. Requires the child
-  /// to already be in the child list at some position. Pass null for before to
-  /// move the child to the end of the child list.
+  /// to already be in the child list at some position. Pass null for `after` to
+  /// move the child to the start of the child list.
   void move(ChildType child, { ChildType after }) {
     assert(child != this);
     assert(after != this);

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

@@ -845,8 +845,9 @@ mixin SchedulerBinding on BindingBase, ServicesBinding {
 
   /// The time stamp for the frame currently being processed.
   ///
-  /// This is only valid while [handleBeginFrame] is running, i.e. while a frame
-  /// is being produced.
+  /// This is only valid while between the start of [handleBeginFrame] and the
+  /// end of the corresponding [handleDrawFrame], i.e. while a frame is being
+  /// produced.
   Duration get currentFrameTimeStamp {
     assert(_currentFrameTimeStamp != null);
     return _currentFrameTimeStamp;

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

@@ -44,6 +44,50 @@ import 'image.dart';
 /// ```
 /// {@end-tool}
 ///
+/// ## Layout behavior
+///
+/// _See [BoxConstraints] for an introduction to box layout models._
+///
+/// Since [Container] combines a number of other widgets each with their own
+/// layout behavior, [Container]'s layout behavior is somewhat complicated.
+///
+/// Summary: [Container] tries, in order: to honor [alignment], to size itself to
+/// the [child], to honor the `width`, `height`, and [constraints], to expand to
+/// fit the parent, to be as small as possible.
+///
+/// More specifically:
+///
+/// If the widget has no child, no `height`, no `width`, no [constraints],
+/// and the parent provides unbounded constraints, then [Container] tries to
+/// size as small as possible.
+///
+/// If the widget has no child and no [alignment], but a `height`, `width`, or
+/// [constraints] are provided, then the [Container] tries to be as small as
+/// possible given the combination of those constraints and the parent's
+/// constraints.
+///
+/// If the widget has no child, no `height`, no `width`, no [constraints], and
+/// no [alignment], but the parent provides bounded constraints, then
+/// [Container] expands to fit the constraints provided by the parent.
+///
+/// If the widget has an [alignment], and the parent provides unbounded
+/// constraints, then the [Container] tries to size itself around the child.
+///
+/// If the widget has an [alignment], and the parent provides bounded
+/// constraints, then the [Container] tries to expand to fit the parent, and
+/// then positions the child within itself as per the [alignment].
+///
+/// Otherwise, the widget has a [child] but no `height`, no `width`, no
+/// [constraints], and no [alignment], and the [Container] passes the
+/// constraints from the parent to the child and sizes itself to match the
+/// child.
+///
+/// The [margin] and [padding] properties also affect the layout, as described
+/// in the documentation for those properties. (Their effects merely augment the
+/// rules described above.) The [decoration] can implicitly increase the
+/// [padding] (e.g. borders in a [BoxDecoration] contribute to the [padding]);
+/// see [Decoration.padding].
+///
 /// See also:
 ///
 ///  * [Ink], which paints a [Decoration] on a [Material], allowing
@@ -182,6 +226,8 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
 /// [padding] (e.g. borders in a [BoxDecoration] contribute to the [padding]);
 /// see [Decoration.padding].
 ///
+/// ## Example
+///
 /// {@tool sample}
 /// This example shows a 48x48 amber square (placed inside a [Center] widget in
 /// case the parent widget has its own opinions regarding the size that the