Add JS Docs

packages/components/src/menu/README.md

@@ -4,6 +4,15 @@
 
 <p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-menu--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
+Menu is a collection of React components that combine to render
+ARIA-compliant [menu](https://www.w3.org/WAI/ARIA/apg/patterns/menu/) and
+[menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/) patterns.
+
+`Menu` itself is a wrapper component and context provider.
+It is responsible for managing the state of the menu and its items, and for
+rendering the `Menu.TriggerButton` (or the `Menu.SubmenuTriggerItem`)
+component, and the `Menu.Popover` component.
+
 ## Props
 
 ### `as`

packages/components/src/menu/index.tsx

@@ -27,6 +27,16 @@ import { MenuTriggerButton } from './trigger-button';
 import { MenuSubmenuTriggerItem } from './submenu-trigger-item';
 import { MenuPopover } from './popover';
 
+/**
+ * Menu is a collection of React components that combine to render
+ * ARIA-compliant [menu](https://www.w3.org/WAI/ARIA/apg/patterns/menu/) and
+ * [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/) patterns.
+ *
+ * `Menu` itself is a wrapper component and context provider.
+ * It is responsible for managing the state of the menu and its items, and for
+ * rendering the `Menu.TriggerButton` (or the `Menu.SubmenuTriggerItem`)
+ * component, and the `Menu.Popover` component.
+ */
 const UnconnectedMenu = ( props: MenuProps ) => {
 	const {
 		children,
@@ -90,42 +100,114 @@ const UnconnectedMenu = ( props: MenuProps ) => {
 	);
 };
 
+/**
+ * Menu is a collection of React components that combine to render
+ * ARIA-compliant [menu](https://www.w3.org/WAI/ARIA/apg/patterns/menu/) and
+ * [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/) patterns.
+ *
+ * `Menu` itself is a wrapper component and context provider.
+ * It is responsible for managing the state of the menu and its items, and for
+ * rendering the `Menu.TriggerButton` (or the `Menu.SubmenuTriggerItem`)
+ * component, and the `Menu.Popover` component.
+ */
 export const Menu = Object.assign(
 	contextConnectWithoutRef( UnconnectedMenu, 'Menu' ),
 	{
 		Context: Object.assign( MenuContext, {
 			displayName: 'Menu.Context',
 		} ),
+		/**
+		 * Renders a menu item inside the `Menu.Popover` or `Menu.Group` components.
+		 *
+		 * It can optionally contain one instance of the `Menu.ItemLabel` component
+		 * and one instance of the `Menu.ItemHelpText` component.
+		 */
 		Item: Object.assign( MenuItem, {
 			displayName: 'Menu.Item',
 		} ),
+		/**
+		 * Renders a radio menu item inside the `Menu.Popover` or `Menu.Group`
+		 * components.
+		 *
+		 * It can optionally contain one instance of the `Menu.ItemLabel` component
+		 * and one instance of the `Menu.ItemHelpText` component.
+		 */
 		RadioItem: Object.assign( MenuRadioItem, {
 			displayName: 'Menu.RadioItem',
 		} ),
+		/**
+		 * Renders a checkbox menu item inside the `Menu.Popover` or `Menu.Group`
+		 * components.
+		 *
+		 * It can optionally contain one instance of the `Menu.ItemLabel` component
+		 * and one instance of the `Menu.ItemHelpText` component.
+		 */
 		CheckboxItem: Object.assign( MenuCheckboxItem, {
 			displayName: 'Menu.CheckboxItem',
 		} ),
+		/**
+		 * Renders a group for menu items.
+		 *
+		 * It should contain one instance of `Menu.GroupLabel` and one or more
+		 * instances of `Menu.Item`, `Menu.RadioItem`, or `Menu.CheckboxItem`.
+		 */
 		Group: Object.assign( MenuGroup, {
 			displayName: 'Menu.Group',
 		} ),
+		/**
+		 * Renders a label in a menu group.
+		 *
+		 * This component should be wrapped with `Menu.Group` so the
+		 * `aria-labelledby` is correctly set on the group element.
+		 */
 		GroupLabel: Object.assign( MenuGroupLabel, {
 			displayName: 'Menu.GroupLabel',
 		} ),
+		/**
+		 * Renders a divider between menu items or menu groups.
+		 */
 		Separator: Object.assign( MenuSeparator, {
 			displayName: 'Menu.Separator',
 		} ),
+		/**
+		 * Renders a menu item's label text. It should be wrapped with `Menu.Item`,
+		 * `Menu.RadioItem`, or `Menu.CheckboxItem`.
+		 */
 		ItemLabel: Object.assign( MenuItemLabel, {
 			displayName: 'Menu.ItemLabel',
 		} ),
+		/**
+		 * Renders a menu item's help text. It should be wrapped with `Menu.Item`,
+		 * `Menu.RadioItem`, or `Menu.CheckboxItem`.
+		 */
 		ItemHelpText: Object.assign( MenuItemHelpText, {
 			displayName: 'Menu.ItemHelpText',
 		} ),
+		/**
+		 * Renders a dropdown menu element that's controlled by a sibling
+		 * `Menu.TriggerButton` component. It renders a popover and automatically
+		 * focuses on items when the menu is shown.
+		 *
+		 * The only valid children of `Menu.Popover` are `Menu.Item`,
+		 * `Menu.RadioItem`, `Menu.CheckboxItem`, `Menu.Group`, `Menu.Separator`,
+		 * and `Menu` (for nested dropdown menus).
+		 */
 		Popover: Object.assign( MenuPopover, {
 			displayName: 'Menu.Popover',
 		} ),
+		/**
+		 * Renders a menu button that toggles the visibility of a sibling
+		 * `Menu.Popover` component when clicked or when using arrow keys.
+		 */
 		TriggerButton: Object.assign( MenuTriggerButton, {
 			displayName: 'Menu.TriggerButton',
 		} ),
+		/**
+		 * Renders a menu item that toggles the visibility of a sibling
+		 * `Menu.Popover` component when clicked or when using arrow keys.
+		 *
+		 * This component is used to create a nested dropdown menu.
+		 */
 		SubmenuTriggerItem: Object.assign( MenuSubmenuTriggerItem, {
 			displayName: 'Menu.SubmenuTriggerItem',
 		} ),