* Added new ButtonBarTheme to replace the deprecated ButtonTheme.bar method.

* Responding to PR feedback.

* [Material] Create material Banner component (#36880)

This PR creates a new material widget for the Banner component. This includes a theme as well. This widget can be dropped into any application, ideally at the top of a listview or scrollview.

(cherry picked from commit 35b6d668)

Removed the use of ButtonTheme.bar in the Banner implementation.

* Updated documentation from PR review comments.

This converts all remaining "## Sample code" segments into snippets, and fixes
the snippet generator to handle multiple snippets in the same dartdoc block
properly.

I also generated, compiled, and ran each of the existing application samples,
and fixed them up to be more useful and/or just run without errors.

This PR fixes these problems with examples:

1. Switching tabs in a snippet now works if there is more than one snippet in
   a single dartdoc block.
2. Generation of snippet code now works if there is more than one snippet.
3. Contrast of text and links in the code sample block has been improved to
   recommended levels.
4. Added five new snippet templates, including a "freeform" template to make
   it possible to show examples that need to change the app instantiation.
5. Fixed several examples to run properly, a couple by adding the "Scaffold"
   widget to the template, a couple by just fixing their code.
6. Fixed visual look of some of the samples when they run by placing many
   samples inside of a Scaffold.
7. In order to make it easier to run locally, changed the sample analyzer to
   remove the contents of the supplied temp directory before running, since
   having files that hang around is problematic (only a problem when running
   locally with the `--temp` argument).
8. Added a `SampleCheckerException` class, and handle sample checking
   exceptions more gracefully.
9. Deprecated the old "## Sample code" designation, and added enforcement for
   the deprecation.
10. Removed unnecessary `new` from templates (although they never appeared in
   the samples thanks to dartfmt, but still).

Fixes #26398
Fixes #27411

[Material] Update the card demo in the Gallery to demonstrate different uses of the Card widget (#27699)

Additionally, this adds a tappable Card example to the Card documentation.

Add Material/Card borderOnForeground flag to allow border to be painted behind the child widget (#27297)

In certain situations, a developer may require the border of a Material to be painted behind its child. For example a Card widget that has a full width image across the top half. In that scenario, the image should ideally be painted above the border with regards to z-position.

This change exposes a flag on Material widget to achieve this behavior. Additionally, the same flag is exposed on Card widget to allow the Card widget to pass this down to its Material.

I added a couple golden tests to verify this new behavior. Goldens are here:
https://github.com/flutter/goldens/commit/46a3d26acbb1b0d72b6b02c30f03b9dbda7d5bdf

This change adds a CardTheme and tests for it.

Golden is here:
https://github.com/flutter/goldens/blob/ec26eeebb44068599c100d3f0c2db7102b047737/packages/flutter/test/material/card_theme.custom_shape.png

From commit:
https://github.com/flutter/goldens/commit/ec26eeebb44068599c100d3f0c2db7102b047737#diff-7564b206413654283ddc5cb59ecd64d4

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

It was causing problems rolling Flutter into Fuchsia

* re-enable lint unnecessary_const

* remove trailling whitespaces

* remove unnecessary const (after merge)

This reverts commit cc1cf13e.

I'm moving the assets in the assets-for-api-docs repo to a slightly different location to help with organization in that repo, so this PR points the doc URLs to the new location. The old assets won't be removed until this PR makes its way to the API docs website.

No documentation or code changes here, other than changing doc image URLs.

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.

* Oct 12 10:12am

* implicit_semantics_test.dart passes

* refactoring

* works in nice

* minor rename

* more doc comments

* to be explicit check better

* fix test

* ++

* ++

* semantics_9_test (BlockSemantics) and implicit_semantics_test are passing

* doc updates

* tiny refactor

* fix static errors in tests

* fix gesture detector

* ++

* ++

* geometry

* ++

* remove noGeometry

* revert test

* +

* all tests but scrolling/clipping pass

* clipping works

* scrolling halfway

* sliver tests pass

* ALL TESTS PASS

* SemanticsNode changed

* docs and tiny fixes

* card test

* more doc comments

* remove missed print

* more tests

* make test pass on Linux

* remove changes to intellij proj file

* review comments

You can't have a newline between the `]` and the `(` in an image in markdown it turns out.

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)

Fixes https://github.com/flutter/flutter/issues/9342

Based on P5's experience

...until people understand them.

Making progress towards document all public APIs in material.dart. We're still
missing a few odds and ends (as well as missing docs in tabs.dart,
tooltip.dart, and two_level_list.dart).

Also, clean up a few interfaces that looked awkward when writing docs.

This patch adds a consistent, simple description for the common pattern of
having a single child widget.