fixup! fix(cdk/menu): update docs to reflect current implementation and add correct role for triggers

Author: mmalerba

src/cdk/menu/menu.md

@@ -24,8 +24,8 @@ The directives in `@angular/cdk/menu` set the appropriate roles on their host el
 Import the `CdkMenuModule` into the `NgModule` in which you want to create menus. You can then apply
 menu directives to build your custom menu. A typical menu consists of the following directives:
 
-- `cdkMenuTriggerFor` - links a trigger element to an `ng-template` containing the menu the trigger opens
-- `cdkMenu` - creates the actual menu content that the trigger will open
+- `cdkMenuTriggerFor` - links a trigger element to an `ng-template` containing the menu to be opened
+- `cdkMenu` - creates the menu content opened by the trigger
 - `cdkMenuItem` - added to each item in the menu
 
 <!-- example({
@@ -37,9 +37,9 @@ Most menu interactions consist of two parts: a trigger and a menu panel.
 
 #### Triggers
 
-`cdkMenuTriggerFor` can be added to any button to make it a trigger for the given menu, or any menu
+You can add `cdkMenuTriggerFor` to any button to make it a trigger for the given menu, or any menu
 item to make it a trigger for a submenu. When adding this directive, be sure to pass a reference to
-the template containing the menu it should open. You can toggle the associated menu using a mouse
+the template containing the menu it should open. Users can toggle the associated menu using a mouse
 or keyboard.
 
 <!-- example({"example":"cdk-menu-standalone-trigger",
@@ -54,21 +54,49 @@ When creating a submenu trigger, add both `cdkMenuItem` and `cdkMenuTriggerFor`
 
 #### Menu content
 
-Menu content is created using the `cdkMenu` or `cdkMenuBar` components. Menus can be always present
-on the page (referred to as an inline menu), or shown on trigger activation (referred to as a popup
-menu). Popup menus must be wrapped in an `ng-template`, as a reference to the ng-template is needed
-to pass to the trigger directive.
+There are two types of menus:
+* _inline menus_ are always present on the page
+* _pop-up menus_ can be toggled to hide or show by the user
 
-Menus should exclusively contain elements with role `menuitem`, `menuitemcheckbox`,
+You can create menus by marking their content element with the `cdkMenu` or `cdkMenuBar`
+directives. You can create several types of menu interaction which are discussed below.
+
+All type of menus should exclusively contain elements with role `menuitem`, `menuitemcheckbox`,
 `menuitemradio`, or `group`. Supporting directives that automatically apply these roles are
 discussed below.
 
 Note that Angular CDK provides no styles; you must add styles as part of building your custom menu.
 
+### Inline Menus
+
+An _inline menu_ is a menu that lives directly on the page rather than a pop-up associated with a
+trigger. You can use an inline menu when you want a persistent menu interaction on a page. Menu
+items within an inline menus are logically grouped together, and you can navigate through them
+using your keyboard. You can create an inline menu by adding the `cdkMenu` directive to the element
+you want to serve as the menu content.
+
+<!-- example({
+  "example": "cdk-menu-inline",
+  "file": "cdk-menu-inline-example.html"
+  }) -->
+
+### Pop-up Menus
+
+You can create pop-up menus using the `cdkMenu` directive as well. Add this directive to the
+element you want to serve as the content for your pop-up menu. Then wrap the content element in an
+`ng-template` and reference the template from the `cdkMenuTriggerFor` property of the trigger. This
+will allow the trigger to show and hide the menu content as needed.
+
+<!-- example({
+  "example": "cdk-menu-standalone-menu",
+  "file": "cdk-menu-standalone-menu-example.html"
+  }) -->
+
 ### Menu Bars
 
-The `CdkMenuBar` directive follows the [ARIA menubar][menubar] spec and behaves similar to a desktop
-app menubar. It consists of at least one `CdkMenuItem` which triggers a submenu.
+Menu bars are a type of inline menu that you can create using the `cdkMenuBar` directive. They
+follow the [ARIA menubar][menubar] spec and behave similarly to a desktop application menubar. Each
+bar consists of at least one `cdkMenuItem` that triggers a submenu.
 
 <!-- example({
   "example": "cdk-menu-menubar",
@@ -77,7 +105,8 @@ app menubar. It consists of at least one `CdkMenuItem` which triggers a submenu.
 
 ### Context Menus
 
-A context menu opens when a user right-clicks within some container element. You can mark a
+A context menus is a type of pop-up menu that doesn't have a traditional trigger element, instead
+it is triggered when a user right-clicks within some container element. You can mark a
 container element with the `cdkContextMenuTriggerFor`, which behaves like `cdkMenuTriggerFor` except
 that it responds to the browser's native `contextmenu` event. Custom context menus appear next to
 the cursor, similarly to native context menus.
@@ -99,37 +128,25 @@ container element will open.
 In the example above, right-clicking on "Inner context menu" will open up the "inner" menu and
 right-clicking inside "Outer context menu" will open up the "outer" menu.
 
-### Inline Menus
-
-An _inline menu_ is a menu that lives directly on the page rather than a pop-up associated with a
-trigger. You can use an inline menu when you want a persistent menu interaction on a page. Menu
-items within an inline menus are logically grouped together, and you can navigate through them
-using your keyboard.
-
-<!-- example({
-  "example": "cdk-menu-inline",
-  "file": "cdk-menu-inline-example.html"
-  }) -->
-
 ### Menu Items
 
-The `cdkMenuItem` directive allows the items to be navigated to via keyboard interaction.
-A menuitem can provide some user defined action by hooking into the `cdkMenuItemTriggered` output.
+The `cdkMenuItem` directive allows users to navigate menu items via keyboard.
+You can add a custom action to a menu item with the `cdkMenuItemTriggered` output.
 
 <!-- example({"example":"cdk-menu-standalone-stateful-menu",
               "file":"cdk-menu-standalone-stateful-menu-example.html", 
               "region":"reset-item"}) -->
 
-You can create nested menus by using a menuitem as the trigger for another menu.
+You can create nested menus by using a menu item as the trigger for another menu.
 
 <!-- example({"example":"cdk-menu-menubar",
               "file":"cdk-menu-menubar-example.html", 
               "region":"file-trigger"}) -->
 
 #### Menu Item Checkboxes
 
-A `cdkMenuItemCheckbox` is a special type of menuitem that behaves as a checkbox. You can use this
-type of menuitem to toggle items on and off. An element with  `cdkMenuItemCheckbox` directive
+A `cdkMenuItemCheckbox` is a special type of menu item that behaves as a checkbox. You can use this
+type of menu item to toggle items on and off. An element with the `cdkMenuItemCheckbox` directive
 does not need the additional `cdkMenuItem` directive.
 
 Checkbox items do not track their own state. You must bind the checked state using the
@@ -142,8 +159,8 @@ don't bind the state it will reset when the menu is closed and re-opened.
 
 #### Menu Item Radios
 
-A `cdkMenuItemRadio` is a special type of menuitem that behaves as a radio button. You can use this
-type of menuitem for menus with exclusively selectable items. An element with the `cdkMenuItemRadio`
+A `cdkMenuItemRadio` is a special type of menu item that behaves as a radio button. You can use this
+type of menu item for menus with exclusively selectable items. An element with the `cdkMenuItemRadio`
 directive does not need the additional `cdkMenuItem` directive.
 
 As with checkbox items, radio items do not track their own state, but you can track it by binding
@@ -170,9 +187,11 @@ If you would like to have unrelated groups of radio buttons within a single menu
 
 ### Smart Menu Aim
 
-`@angular/cdk/menu` intelligently predicts when a user intends to navigate to an open submenu and
-prevent premature closeouts. This functionality prevents users from having to hunt through the open
-menus in a maze-like fashion to reach their destination.
+`@angular/cdk/menu` is capable of intelligently predicting when a user intends to navigate to an
+open submenu and preventing premature closeouts. This functionality prevents users from having to
+hunt through the open menus in a maze-like fashion to reach their destination. To enable this
+feature for a menu and its sub-menus, add the `cdkMenuTargetAim` directive to the `cdkMenu` or
+`cdkMenuBar` element.
 
 ![menu aim diagram][diagram]