refactor: update snippets/embedded example comments in material docs md to reflect new API (badge, toolbar) (#19669)

* badge

* toolbar

Author: annieyw

src/components-examples/material/badge/badge-overview/badge-overview-example.html

@@ -1,21 +1,43 @@
 <p>
+<!-- #docregion mat-badge-overlap -->
   <span matBadge="4" matBadgeOverlap="false">Text with a badge</span>
+<!-- #enddocregion mat-badge-overlap -->
+</p>
+
+<p>
+<!-- #docregion mat-badge-size -->
+    <span matBadge="1" matBadgeSize="large">Text with large badge</span>
+<!-- #enddocregion mat-badge-size -->
 </p>
 
 <p>
   Button with a badge on the left
+<!-- #docregion mat-badge-position -->
   <button mat-raised-button color="primary"
       matBadge="8" matBadgePosition="before" matBadgeColor="accent">
     Action
   </button>
+<!-- #enddocregion mat-badge-position -->
+</p>
+
+<p>
+    Button toggles badge visibility
+<!-- #docregion mat-badge-hide -->
+    <button mat-raised-button matBadge="7" [matBadgeHidden]="hidden" (click)="toggleBadgeVisibility()">
+        Hide
+    </button>
+<!-- #enddocregion mat-badge-hide -->
 </p>
 
 <p>
   Icon with a badge
+<!-- #dorection mat-badge-color -->
   <mat-icon matBadge="15" matBadgeColor="warn">home</mat-icon>
+<!-- #enddocregion mat-badge-color -->
     <!-- Include text description of the icon's meaning for screen-readers -->
     <span class="cdk-visually-hidden">
       Example with a home icon with overlaid badge showing the number 15
     </span>
 </p>
 
+

src/components-examples/material/badge/badge-overview/badge-overview-example.ts

@@ -8,4 +8,10 @@ import {Component} from '@angular/core';
   templateUrl: 'badge-overview-example.html',
   styleUrls: ['badge-overview-example.css'],
 })
-export class BadgeOverviewExample {}
+export class BadgeOverviewExample {
+  hidden = false;
+
+  toggleBadgeVisibility() {
+    this.hidden = !this.hidden;
+  }
+}

src/components-examples/material/toolbar/toolbar-multirow/toolbar-multirow-example.css

@@ -1,7 +1,8 @@
 .example-icon {
   padding: 0 14px;
 }
-
+/* #docregion toolbar-position-content-style */
 .example-spacer {
   flex: 1 1 auto;
 }
+/* #enddocregion toolbar-position-content-style */

src/components-examples/material/toolbar/toolbar-multirow/toolbar-multirow-example.html

@@ -1,13 +1,17 @@
 <mat-toolbar color="primary">
+<!-- #docregion toolbar-row -->
   <mat-toolbar-row>
     <span>Custom Toolbar</span>
   </mat-toolbar-row>
+<!-- #enddocregion toolbar-row -->
 
+<!-- #docregion toolbar-position-content -->
   <mat-toolbar-row>
     <span>Second Line</span>
     <span class="example-spacer"></span>
     <mat-icon class="example-icon" aria-hidden="false" aria-label="Example user verified icon">verified_user</mat-icon>
   </mat-toolbar-row>
+<!-- #enddocregion toolbar-position-content -->
 
   <mat-toolbar-row>
     <span>Third Line</span>

src/components-examples/material/toolbar/toolbar-overview/toolbar-overview-example.html

@@ -1,3 +1,11 @@
+<p>
+<!-- #docregion toolbar-simple -->
+  <mat-toolbar>
+    <span>My Application</span>
+  </mat-toolbar>
+<!-- #enddocregion toolbar-simple -->
+</p>
+
 <p>
   <mat-toolbar>
    <button mat-icon-button class="example-icon" aria-label="Example icon-button with menu icon">

src/material/badge/badge.md

@@ -8,48 +8,40 @@ another object.
 By default, the badge will be placed `above after`. The direction can be changed by defining
 the attribute `matBadgePosition` follow by `above|below` and `before|after`.
 
-```html
-<mat-icon matBadge="22" matBadgePosition="above after">home</mat-icon>
-```
+<!-- example({"example":"badge-overview",
+              "file":"badge-overview-example.html", 
+              "region":"mat-badge-position"}) -->
 
 The overlap of the badge in relation to its inner contents can also be defined
 using the `matBadgeOverlap` tag. Typically, you want the badge to overlap an icon and not
 a text phrase. By default it will overlap.
 
-```html
-<h1 matBadge="11" matBadgeOverlap="false">
-  Email
-</h1>
-```
+<!-- example({"example":"badge-overview",
+              "file":"badge-overview-example.html", 
+              "region":"mat-badge-overlap"}) -->
 
 ### Badge sizing
 The badge has 3 sizes: `small`, `medium` and `large`. By default, the badge is set to `medium`.
 You can change the size by adding `matBadgeSize` to the host element.
 
-```html
-<h1 matBadge="11" matBadgeSize="large">
-  Email
-</h1>
-```
+<!-- example({"example":"badge-overview",
+              "file":"badge-overview-example.html", 
+              "region":"mat-badge-size"}) -->
 
 ### Badge visibility
 The badge visibility can be toggled programmatically by defining `matBadgeHidden`.
 
-```html
-<h1 matBadge="11" [matBadgeHidden]="!visible">
-  Email
-</h1>
-```
+<!-- example({"example":"badge-overview",
+              "file":"badge-overview-example.html", 
+              "region":"mat-badge-hide"}) -->
 
 ### Theming
 Badges can be colored in terms of the current theme using the `matBadgeColor` property to set the
 background color to `primary`, `accent`, or `warn`.
 
-```html
-<mat-icon matBadge="22" matBadgeColor="accent">
-  home
-</mat-icon>
-```
+<!-- example({"example":"badge-overview",
+              "file":"badge-overview-example.html", 
+              "region":"mat-badge-color"}) -->
 
 ### Accessibility
 Badges should be given a meaningful description via `matBadgeDescription`. This description will be

src/material/toolbar/toolbar.md

@@ -7,29 +7,19 @@
 In the most situations, a toolbar will be placed at the top of your application and will only 
 have a single row that includes the title of your application.
 
-```html
-<mat-toolbar>
-  <span>My Application</span>
-</mat-toolbar>
-```
+<!-- example({"example":"toolbar-overview",
+              "file":"toolbar-overview-example.html", 
+              "region":"toolbar-simple"}) -->
 
 ### Multiple rows
 
 The Material Design specifications describe that toolbars can also have multiple rows. Creating
 toolbars with multiple rows in Angular Material can be done by placing `<mat-toolbar-row>` elements
 inside of a `<mat-toolbar>`.
 
-```html
-<mat-toolbar>  
-  <mat-toolbar-row>
-    <span>First Row</span>
-  </mat-toolbar-row>
-  
-  <mat-toolbar-row>
-    <span>Second Row</span>
-  </mat-toolbar-row>
-</mat-toolbar>
-```
+<!-- example({"example":"toolbar-multirow",
+              "file":"toolbar-multirow-example.html", 
+              "region":"toolbar-row"}) -->
 
 **Note**: Placing content outside of a `<mat-toolbar-row>` when multiple rows are specified is not
 supported.
@@ -40,23 +30,14 @@ position the content as it suits their application.
 
 A common pattern is to position a title on the left with some actions on the right. This can be
 easily accomplished with `display: flex`:
-```html
-<mat-toolbar color="primary">
-  <span>Application Title</span>
-  
-  <!-- This fills the remaining space of the current row -->
-  <span class="example-fill-remaining-space"></span>
-  
-  <span>Right Aligned Text</span>
-</mat-toolbar>
-```
-```scss
-.example-fill-remaining-space {
-  /* This fills the remaining space, by using flexbox. 
-     Every toolbar row uses a flexbox row layout. */
-  flex: 1 1 auto;
-}
-```
+
+<!-- example({"example":"toolbar-multirow",
+              "file":"toolbar-multirow-example.html", 
+              "region":"toolbar-position-content"}) -->
+              
+<!-- example({"example":"toolbar-multirow",
+              "file":"toolbar-multirow-example.css", 
+              "region":"toolbar-position-content-style"}) -->
 
 ### Theming
 The color of a `<mat-toolbar>` can be changed by using the `color` property. By default, toolbars