refactor: update snippets/embedded example comments in material docs md to reflect new API (autocomplete, datepicker, and menu) (#19283)

* update autocomplete and datepicker snippet comments

* minor structural changes to docs surrounding snippet examples

* update to use regions

Author: annieyw

src/components-examples/material/autocomplete/autocomplete-optgroup/autocomplete-optgroup-example.html

@@ -6,12 +6,14 @@
            formControlName="stateGroup"
            required
            [matAutocomplete]="autoGroup">
+<!-- #docregion mat-autocomplete -->
       <mat-autocomplete #autoGroup="matAutocomplete">
         <mat-optgroup *ngFor="let group of stateGroupOptions | async" [label]="group.letter">
           <mat-option *ngFor="let name of group.names" [value]="name">
             {{name}}
           </mat-option>
       </mat-optgroup>
     </mat-autocomplete>
+<!-- #enddocregion mat-autocomplete -->
   </mat-form-field>
 </form>

src/components-examples/material/autocomplete/autocomplete-simple/autocomplete-simple-example.html

@@ -1,15 +1,19 @@
 <form class="example-form">
   <mat-form-field class="example-full-width">
+<!-- #docregion input -->
     <input type="text"
            placeholder="Pick one"
            aria-label="Number"
            matInput
            [formControl]="myControl"
            [matAutocomplete]="auto">
+<!-- #enddocregion input -->
+<!-- #docregion mat-autocomplete -->
     <mat-autocomplete #auto="matAutocomplete">
       <mat-option *ngFor="let option of options" [value]="option">
         {{option}}
       </mat-option>
     </mat-autocomplete>
+<!-- #enddocregion mat-autocomplete -->
   </mat-form-field>
 </form>

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

@@ -1,6 +1,8 @@
 <mat-form-field>
   <mat-label>Choose a date</mat-label>
+<!-- #docregion toggle -->
   <input matInput [matDatepicker]="picker">
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
+<!-- #enddocregion toggle -->
 </mat-form-field>

src/material/autocomplete/autocomplete.md

@@ -2,51 +2,31 @@ The autocomplete is a normal text input enhanced by a panel of suggested options
 
 ### Simple autocomplete
 
-Start by adding a regular `matInput` to your template. Let's assume you're using the `formControl`
-directive from `ReactiveFormsModule` to track the value of the input.
+Start by creating the autocomplete panel and the options displayed inside it. Each option should be
+defined by a `mat-option` tag. Set each option's value property to whatever you'd like the value
+of the text input to be when that option is selected.
+
+<!-- example({"example":"autocomplete-simple",
+              "file":"autocomplete-simple-example.html", 
+              "region":"mat-autocomplete"}) -->
+
+Next, create the input and set the `matAutocomplete` input to refer to the template reference we assigned 
+to the autocomplete. Let's assume you're using the `formControl` directive from `ReactiveFormsModule` to 
+track the value of the input.
 
 > Note: It is possible to use template-driven forms instead, if you prefer. We use reactive forms
 in this example because it makes subscribing to changes in the input's value easy. For this
 example, be sure to import `ReactiveFormsModule` from `@angular/forms` into your `NgModule`.
 If you are unfamiliar with using reactive forms, you can read more about the subject in the
 [Angular documentation](https://angular.io/guide/reactive-forms).
 
-*my-comp.html*
-```html
-<mat-form-field>
-  <input type="text" matInput [formControl]="myControl">
-</mat-form-field>
-```
-
-Next, create the autocomplete panel and the options displayed inside it. Each option should be
-defined by a `mat-option` tag. Set each option's value property to whatever you'd like the value
-of the text input to be upon that option's selection.
-
-*my-comp.html*
-```html
-<mat-autocomplete>
-  <mat-option *ngFor="let option of options" [value]="option">
-    {{ option }}
-  </mat-option>
-</mat-autocomplete>
-```
-
 Now we'll need to link the text input to its panel. We can do this by exporting the autocomplete
 panel instance into a local template variable (here we called it "auto"), and binding that variable
 to the input's `matAutocomplete` property.
 
-*my-comp.html*
-```html
-<mat-form-field>
-  <input type="text" matInput [formControl]="myControl" [matAutocomplete]="auto">
-</mat-form-field>
-
-<mat-autocomplete #auto="matAutocomplete">
-  <mat-option *ngFor="let option of options" [value]="option">{{option}}</mat-option>
-</mat-autocomplete>
-```
-
-<!-- example(autocomplete-simple) -->
+<!-- example({"example":"autocomplete-simple",
+              "file":"autocomplete-simple-example.html", 
+              "region":"input"}) -->
 
 ### Adding a custom filter
 
@@ -127,18 +107,9 @@ autocomplete is attached to using the `matAutocompleteOrigin` directive together
 
 ### Option groups
 `mat-option` can be collected into groups using the `mat-optgroup` element:
-<!-- example(autocomplete-optgroup) -->
-
-
-```html
-<mat-autocomplete #auto="matAutocomplete">
-  <mat-optgroup *ngFor="let group of filteredGroups | async" [label]="group.name">
-    <mat-option *ngFor="let option of group.options" [value]="option">
-      {{option.name}}
-    </mat-option>
-  </mat-optgroup>
-</mat-autocomplete>
-```
+<!-- example({"example":"autocomplete-optgroup",
+              "file":"autocomplete-optgroup-example.html", 
+              "region":"mat-autocomplete"}) -->
 
 ### Accessibility
 The input for an autocomplete without text or labels should be given a meaningful label via

src/material/datepicker/datepicker.md

@@ -8,29 +8,17 @@ the calendar. It is made up of several components and directives that work toget
 A datepicker is composed of a text input and a calendar pop-up, connected via the `matDatepicker`
 property on the text input.
 
-```html
-<input [matDatepicker]="myDatepicker">
-<mat-datepicker #myDatepicker></mat-datepicker>
-```
+There is also an optional datepicker toggle button that gives the user an easy way to open the datepicker pop-up.
 
-An optional datepicker toggle button is available. A toggle can be added to the example above:
-
-```html
-<input [matDatepicker]="myDatepicker">
-<mat-datepicker-toggle [for]="myDatepicker"></mat-datepicker-toggle>
-<mat-datepicker #myDatepicker></mat-datepicker>
-```
+<!-- example({"example":"datepicker-overview",
+              "file":"datepicker-overview-example.html", 
+              "region":"toggle"}) -->
 
 This works exactly the same with an input that is part of an `<mat-form-field>` and the toggle
 can easily be used as a prefix or suffix on the Material input:
 
-```html
-<mat-form-field>
-  <input matInput [matDatepicker]="myDatepicker">
-  <mat-datepicker-toggle matSuffix [for]="myDatepicker"></mat-datepicker-toggle>
-  <mat-datepicker #myDatepicker></mat-datepicker>
-</mat-form-field>
-```
+<!-- example({"example":"datepicker-overview",
+              "file":"datepicker-overview-example.html"}) -->
 
 If you want to customize the icon that is rendered inside the `mat-datepicker-toggle`, you can do so
 by using the `matDatepickerToggleIcon` directive: