* Embedding new diarams for API docs: Container, ListView, Align.

* Moving the diagrams to be enclosed within the snippet windows.

* Fixed wording for the alt image text.

* Updating sample code for container to match forthcoming diagrams in assets-for-api-docs.

* Analyzer unhappy with Colors, fixing.

* Resolving push conflict (hopefully)

* Analyzer fix.

* Corrected color to match brand gallery

* Fixing wrap and indentation.

* add trailing commas on list/map/parameters

* add trailing commas on Invocation with nb of arg>1

* add commas for widget containing widgets

* add trailing commas if instantiation contains trailing comma

* revert bad change

Fix the spelling errors in the dartdocs for the framework.

There are no functionality changes here, just documentation fixes.

This converts existing ## Sample code samples to {@tool sample}...{@end-tool} form.

Also:
1. Fixed a minor bug in analyze-sample-code.dart
2. Made the snippet tool only insert descriptions if the description is non-empty.
3. Moved the Card diagram to before the code sample.

This rewrites the sample code analysis script to be a little less of a hack (but still not pretty), and to handle snippets as well.

It also changes the semantics of how sample code is handled: the namespace for the sample code is now limited to the file that it appears in, so some additional "Examples can assume:" blocks were added. The upside of this is that there will be far fewer name collisions.

I fixed the output too: no longer will you get 4000 lines of numbered output with the error at the top and have to grep for the actual problem. It gives the filename and line number of the original location of the code (in the comment in the tree), and prints out the source code on the line that caused the problem along with the error.

For snippets, it prints out the location of the start of the snippet and the source code line that causes the problem. It can't print out the original line, because snippets get formatted when they are written, so the line might not be in the same place.

* enable lint unnecessary_new

* fix tests

* fix tests

* fix tests

* lint unnecessary_new on samples

* fix tests

This provides a way to draw colors, images, and general decorations on Material widgets, without interfering with InkWells that are further descendants of the widget.

This thus provides a cleaner way to solve the issue of FlatButtons and InkWells not working when placed over Image widgets than the old hack of introducing a transparency Material.

Fixes #3782.

Also, some fixes to documentation, and remove a redundant property on the Image widget.

This attempts to apply some of what we learnt from UX studies, namely
that people wonder how to add multiple children to widget that take
one child.

UnconstrainedBox will allow its child to size itself as if it had no constraints, and then attempt to fit around that object, until its own constraints are exceeded, in which case it will clip and display an overflow warning.

I also factored out DebugOverflowIndicator, which will draw overflow indicators on containers which overflow but aren't expected to.

Unlike FractionalOffset, Alignment uses the center as the zero of the
coordinate system, which makes the RTL math work out much cleaner.

Also, make FractionalOffset into a subclass of Alignment so that clients
can continue to use FractionalOffset.

Diagnostics object is.

Fixes #11373

* Introduce a Directionality inherited widget which sets the ambient LTR vs RTL mode (defaulting to null, which means you cannot use directionality-influenced values).

* Make it possible to configure Padding (including Container.padding and Container.margin) using a directionality-agnostic EdgeInsets variant.

* Provide textDirection and verticalDirection controls on Row and Column to make them RTL-aware.

* Introduce a variant of FractionalOffset based on the EdgeInsets variant. Not yet actually used.

* Fix all the tests that depended on Row defaulting to LTR.

Add Diagnosticable base class and documentation

Refactor RenderObject.toStringDeep and Widget.toStringDeep code to use DiagnosticsNode.

* preview of prefer_asserts_in_initializer_list lint

* fix issue

Minor fixes throughout, e.g. removing trailing commas from the end of sample code expressions, changing headings to "sample code" more consistently, removing stale todos, fix typos in a private method name, minor grammar fixes, added some clarifications to CircularProgressIndicator, LinearProgressIndicator, CrossAxisAlignment, added some cross-references to various members, made it slightly clearer that layout algorithms are implementation details.

Clarified "elevation" throughout.

Added docs to InkResponse and InkWell.

Added sample code for: SliverAppBar, Card, ListTile, EdgeInsets, Row, Column, CustomScrollView, ListView, SliverFixedExtentList, and SliverGrid.

Fixes #10317.
Fixes #10316.
Fixes #10267. (sort of, see comment therein)
Fixes #9331. (sort of, see comment therein)
Fixes #9407. (sort of, see comment therein)

backgroundColor -> color
backgroundImage -> image
BackgroundImage -> DecorationImage

Aggressively apply the const lint.

Fixes https://github.com/flutter/flutter/pull/8643

Fixes https://github.com/flutter/flutter/issues/8804 by adding a test
to verify that Material elevation changes animate.

Also tweak some dartdocs, add some trailing commas, improve some
toString output, make the inkwell test agnostic to the PhysicalModel
logic, and move the material buttons test to the material test
directory.

Covers lib/ in package:flutter.

It's common to just want a simple colored box. Simple thing should be simple,
so this patch adds a convenience argument to Continer for creating a box
decoration that is just a color.

Fixes #5555