refactor: update snippets/embedded example comments in material docs md to reflect new API (chips, menu, tabs)

src/components-examples/material/menu/menu-nested/menu-nested-example.html

@@ -1,5 +1,5 @@
 <button mat-button [matMenuTriggerFor]="animals">Animal index</button>
-
+<!-- #docregion sub-menu -->
 <mat-menu #animals="matMenu">
   <button mat-menu-item [matMenuTriggerFor]="vertebrates">Vertebrates</button>
   <button mat-menu-item [matMenuTriggerFor]="invertebrates">Invertebrates</button>
@@ -12,6 +12,7 @@
   <button mat-menu-item>Birds</button>
   <button mat-menu-item>Mammals</button>
 </mat-menu>
+<!-- #enddocregion sub-menu -->
 
 <mat-menu #invertebrates="matMenu">
   <button mat-menu-item>Insects</button>

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

@@ -1,4 +1,6 @@
+<!-- #docregion mat-menu-trigger-for -->
 <button mat-button [matMenuTriggerFor]="menu">Menu</button>
+<!-- #enddocregion mat-menu-trigger-for -->
 <mat-menu #menu="matMenu">
   <button mat-menu-item>Item 1</button>
   <button mat-menu-item>Item 2</button>

src/components-examples/material/menu/menu-position/menu-position-example.html

@@ -1,5 +1,7 @@
 <button mat-button [matMenuTriggerFor]="aboveMenu">Above</button>
+<!-- #docregion menu-position -->
 <mat-menu #aboveMenu="matMenu" yPosition="above">
+<!-- #enddocregion menu-position -->
   <button mat-menu-item>Item 1</button>
   <button mat-menu-item>Item 2</button>
 </mat-menu>

src/components-examples/material/tabs/tab-group-align/tab-group-align-example.html

@@ -1,4 +1,6 @@
+<!-- #docregion align-start -->
 <mat-tab-group mat-align-tabs="start">
+<!-- #enddocregion align-start -->
   <mat-tab label="First">Content 1</mat-tab>
   <mat-tab label="Second">Content 2</mat-tab>
   <mat-tab label="Third">Content 3</mat-tab>

src/components-examples/material/tabs/tab-group-animations/tab-group-animations-example.html

@@ -7,7 +7,9 @@ <h3>No animation</h3>
 </mat-tab-group>
 
 <h3>Very slow animation</h3>
+<!-- #docregion slow-animation-duration -->
 <mat-tab-group animationDuration="2000ms">
+<!-- #enddocregion slow-animation-duration -->
   <mat-tab label="First">Content 1</mat-tab>
   <mat-tab label="Second">Content 2</mat-tab>
   <mat-tab label="Third">Content 3</mat-tab>

src/components-examples/material/tabs/tab-group-custom-label/tab-group-custom-label-example.html

@@ -1,9 +1,11 @@
 <mat-tab-group>
   <mat-tab>
+<!-- #docregion label-directive -->
     <ng-template mat-tab-label>
       <mat-icon class="example-tab-icon">thumb_up</mat-icon>
       First
     </ng-template>
+<!-- #enddocregion label-directive -->
     Content 1
   </mat-tab>
 

src/components-examples/material/tabs/tab-group-dynamic-height/tab-group-dynamic-height-example.html

@@ -1,4 +1,6 @@
+<!-- #docregion dynamic-height -->
 <mat-tab-group dynamicHeight>
+<!-- #enddocregion dynamic-height -->
   <mat-tab label="Short tab">
     <div class="example-small-box mat-elevation-z4">
       Small content

src/components-examples/material/tabs/tab-group-lazy-loaded/tab-group-lazy-loaded-example.html

@@ -1,9 +1,11 @@
 <mat-tab-group>
+<!-- #docregion mat-tab-content -->
   <mat-tab label="First">
     <ng-template matTabContent>
       Content 1 - Loaded: {{getTimeLoaded(1) | date:'medium'}}
     </ng-template>
   </mat-tab>
+<!-- #enddocregion mat-tab-content -->
   <mat-tab label="Second">
     <ng-template matTabContent>
       Content 2 - Loaded: {{getTimeLoaded(2) | date:'medium'}}

src/components-examples/material/tabs/tab-nav-bar-basic/tab-nav-bar-basic-example.html

@@ -1,9 +1,11 @@
+<!-- #docregion mat-tab-nav -->
 <nav mat-tab-nav-bar [backgroundColor]="background">
   <a mat-tab-link *ngFor="let link of links"
      (click)="activeLink = link"
      [active]="activeLink == link"> {{link}} </a>
   <a mat-tab-link disabled>Disabled Link</a>
 </nav>
+<!-- #enddocregion mat-tab-nav -->
 
 <button mat-raised-button class="example-action-button" (click)="toggleBackground()">
   Toggle background

src/material/chips/chips.md

@@ -1,14 +1,7 @@
 `<mat-chip-list>` displays a list of values as individual, keyboard accessible, chips.
 
-<!-- example(chips-overview) -->
-
-```html
-<mat-chip-list>
-  <mat-chip>Papadum</mat-chip>
-  <mat-chip>Naan</mat-chip>
-  <mat-chip>Dal</mat-chip>
-</mat-chip-list>
-```
+<!-- example{{"example":"chips-overview",
+              "file":"chips-overview-example.html"}) -->
 
 ### Unstyled chips
 By default, `<mat-chip>` has Material Design styles applied. For a chip with no styles applied,
@@ -59,13 +52,8 @@ also gain focus when clicked, ensuring keyboard navigation starts at the appropr
 If you want the chips in the list to be stacked vertically, instead of horizontally, you can apply
 the `mat-chip-list-stacked` class, as well as the `aria-orientation="vertical"` attribute:
 
-```html
-<mat-chip-list class="mat-chip-list-stacked" aria-orientation="vertical">
-  <mat-chip>Papadum</mat-chip>
-  <mat-chip>Naan</mat-chip>
-  <mat-chip>Dal</mat-chip>
-</mat-chip-list>
-```
+<!-- example({"example":"chips-stacked",
+              "file":"chips-stacked-example.html")} -->
 
 ### Specifying global configuration defaults
 Default options for the chips module can be specified using the `MAT_CHIPS_DEFAULT_OPTIONS`

src/material/menu/menu.md

@@ -4,16 +4,9 @@
 
 By itself, the `<mat-menu>` element does not render anything. The menu is attached to and opened
 via application of the `matMenuTriggerFor` directive:
-```html
-<mat-menu #appMenu="matMenu">
-  <button mat-menu-item>Settings</button>
-  <button mat-menu-item>Help</button>
-</mat-menu>
-
-<button mat-icon-button [matMenuTriggerFor]="appMenu">
-  <mat-icon>more_vert</mat-icon>
-</button>
-```
+<!-- example({"example":"menu-overview",
+              "file":"menu-overview-example.html",
+              "region:"mat-menu-trigger-for"}) -->
 
 ### Toggling the menu programmatically
 The menu exposes an API to open/close programmatically. Please note that in this case, an
@@ -32,23 +25,8 @@ class MyComponent {
 ### Icons
 Menus support displaying `mat-icon` elements before the menu item text.
 
-*my-comp.html*
-```html
-<mat-menu #menu="matMenu">
-  <button mat-menu-item>
-    <mat-icon>dialpad</mat-icon>
-    <span>Redial</span>
-  </button>
-  <button mat-menu-item disabled>
-    <mat-icon>voicemail</mat-icon>
-    <span>Check voicemail</span>
-  </button>
-  <button mat-menu-item>
-    <mat-icon>notifications_off</mat-icon>
-    <span>Disable alerts</span>
-  </button>
-</mat-menu>
-```
+<!-- example({"example":"menu-icons",
+              "file":"menu-icons-example.html")} -->
 
 ### Customizing menu position
 
@@ -57,43 +35,19 @@ its trigger. The position can be changed using the `xPosition` (`before | after`
 (`above | below`) attributes. The menu can be forced to overlap the trigger using the
 `overlapTrigger` attribute.
 
-```html
-<mat-menu #appMenu="matMenu" yPosition="above">
-  <button mat-menu-item>Settings</button>
-  <button mat-menu-item>Help</button>
-</mat-menu>
-
-<button mat-icon-button [matMenuTriggerFor]="appMenu">
-  <mat-icon>more_vert</mat-icon>
-</button>
-```
-
-<!-- example(menu-position) -->
+<!-- example({"example":"menu-position",
+              "file":"menu-position-example.html",
+              "region":"menu-position")} -->
 
 ### Nested menu
 
 Material supports the ability for an `mat-menu-item` to open a sub-menu. To do so, you have to define
 your root menu and sub-menus, in addition to setting the `[matMenuTriggerFor]` on the `mat-menu-item`
 that should trigger the sub-menu:
 
-```html
-<mat-menu #rootMenu="matMenu">
-  <button mat-menu-item [matMenuTriggerFor]="subMenu">Power</button>
-  <button mat-menu-item>System settings</button>
-</mat-menu>
-
-<mat-menu #subMenu="matMenu">
-  <button mat-menu-item>Shut down</button>
-  <button mat-menu-item>Restart</button>
-  <button mat-menu-item>Hibernate</button>
-</mat-menu>
-
-<button mat-icon-button [matMenuTriggerFor]="rootMenu">
-  <mat-icon>more_vert</mat-icon>
-</button>
-```
-
-<!-- example(menu-nested) -->
+<!-- example({"example":"menu-nested",
+              "file":"menu-nested-example.html",
+              "region":"sub-menu")} -->
 
 ### Lazy rendering
 By default, the menu content will be initialized even when the panel is closed. To defer

src/material/tabs/tabs.md

@@ -19,62 +19,32 @@ the header, usually through keyboard navigation.
 
 If a tab's label is only text then the simple tab-group API can be used.
 
-```html
-<mat-tab-group>
-  <mat-tab label="One">
-    <h1>Some tab content</h1>
-    <p>...</p>
-  </mat-tab>
-  <mat-tab label="Two">
-    <h1>Some more tab content</h1>
-    <p>...</p>
-  </mat-tab>
-</mat-tab-group>
-```
+<!-- example({"example":"tab-group-basic",
+              "file":"tab-group-basic.html"}) -->
 
 For more complex labels, add a template with the `mat-tab-label` directive inside the `mat-tab`.
 
-```html
-<mat-tab-group>
-  <mat-tab>
-    <ng-template mat-tab-label>
-      The <em>best</em> pasta
-    </ng-template>
-    <h1>Best pasta restaurants</h1>
-    <p>...</p>
-  </mat-tab>
-  <mat-tab>
-    <ng-template mat-tab-label>
-      <mat-icon>thumb_down</mat-icon> The worst sushi
-    </ng-template>
-    <h1>Terrible sushi restaurants</h1>
-    <p>...</p>
-  </mat-tab>
-</mat-tab-group>
-```
+<!-- example({"example":"tab-group-custom-label",
+              "file":"tab-group-custom-label-example.html",
+              "region":"label-directive"}) -->
 
 ### Dynamic Height
 
 By default, the tab group will not change its height to the height of the currently active tab. To
 change this, set the `dynamicHeight` input to true. The tab body will animate its height according
  to the height of the active tab.
+
+ <!-- example({"example":"tab-group-dynamic-height",
+               "file":"tab-group-dynamic-height-example.html",
+               "region":"dynamic-height"}) -->
 
 ### Tabs and navigation
 While `<mat-tab-group>` is used to switch between views within a single route, `<nav mat-tab-nav-bar>`
 provides a tab-like UI for navigating between routes.
-```html
-<nav mat-tab-nav-bar>
-  <a mat-tab-link
-     *ngFor="let link of navLinks"
-     [routerLink]="link.path"
-     routerLinkActive #rla="routerLinkActive"
-     [active]="rla.isActive">
-    {{link.label}}
-  </a>
-</nav>
-
-<router-outlet></router-outlet>
-```
+
+ <!-- example({"example":"tab-nav-bar-basic",
+               "file":"tab-nav-bar-basic-example.html",
+               "region":"mat-tab-nav"}) -->
 
 The `tab-nav-bar` is not tied to any particular router; it works with normal `<a>` elements and uses
 the `active` property to determine which tab is currently active. The corresponding
@@ -93,33 +63,26 @@ to lazy load the tab's content.
 Tab contents can be lazy loaded by declaring the body in a `ng-template`
 with the `matTabContent` attribute.
 
-```html
-<mat-tab-group>
-  <mat-tab label="First">
-    <ng-template matTabContent>
-      The First Content
-    </ng-template>
-  </mat-tab>
-  <mat-tab label="Second">
-    <ng-template matTabContent>
-      The Second Content
-    </ng-template>
-  </mat-tab>
-</mat-tab-group>
-```
+ <!-- example({"example":"tab-group-lazy-loaded",
+               "file":"tab-group-lazy-loaded-example.html",
+               "region":"mat-tab-content"}) -->
 
 ### Label alignment
 If you want to align the tab labels in the center or towards the end of the container, you can
 do so using the `[mat-align-tabs]` attribute.
 
-<!-- example(tab-group-align) -->
+ <!-- example({"example":"tab-group-align",
+               "file":"tab-group-align-example.html",
+               "region":"align-start"}) -->
 
 ### Controlling the tab animation
 You can control the duration of the tabs' animation using the `animationDuration` input. If you
 want to disable the animation completely, you can do so by setting the properties to `0ms`. The
 duration can be configured globally using the `MAT_TABS_CONFIG` injection token.
 
-<!-- example(tab-group-animations) -->
+ <!-- example({"example":"tab-group-animations",
+               "file":"tab-group-animations-example.html",
+               "region":"slow-animation-duration"}) -->
 
 ### Accessibility
 `<mat-tab-group>` and `<mat-nav-tab-bar>` use different interaction patterns. The