From 8325af7fed736e6a744a86de07b6ffbe12d821b9 Mon Sep 17 00:00:00 2001
From: Cody Mikol <codymikol@gmail.com>
Date: Thu, 21 Feb 2019 21:30:29 -0500
Subject: [PATCH] docs($mdMenu): add documentation for $mdMenu

currently there is no documentation.

Fixes: #11610
---
 src/components/menu/js/menuServiceProvider.js | 54 ++++++++++++++++---
 1 file changed, 48 insertions(+), 6 deletions(-)

diff --git a/src/components/menu/js/menuServiceProvider.js b/src/components/menu/js/menuServiceProvider.js
index 3650f3cbb5d..9096f731bc6 100644
--- a/src/components/menu/js/menuServiceProvider.js
+++ b/src/components/menu/js/menuServiceProvider.js
@@ -2,14 +2,56 @@ angular
   .module('material.components.menu')
   .provider('$mdMenu', MenuProvider);
 
+/** Handles behavior for a menu while it is open, including:
+*
+*  - handling animating the menu opening/closing
+*  - handling key/mouse events on the menu element
+*  - handling enabling/disabling scroll while the menu is open
+*  - handling redrawing during resizes and orientation changes
+*/
+
+/**
+ * @ngdoc service
+ * @name $mdMenu
+ * @module material.components.menu
+ *
+ * @description
+ * `$mdMenu` is a service that is available within the scope of an `md-menu` directive.
+ *
+ * ## Usage
+ *
+ * <hljs lang="html">
+ *   <md-menu>
+ *      <!--Clicking the button will open the menu-->
+ *     <md-button ng-click="$mdMenu.open($event)">
+ *       Open
+ *     </md-button>
+ *     <!--Moving the mouse off will close the menu-->
+ *     <md-menu-content ng-mouseleave="$mdMenu.close()">
+ *       <md-menu-item>
+ *           <md-button ng-click="$mdMenu.close()">Clicking me will also close the menu</md-button>
+ *       </md-menu-item>
+ *     </md-menu-content>
+ *   </md-menu>
+ * </hljs>
+ */
+
+/**
+ * @ngdoc method
+ * @name $mdMenu#open
+ * @param {$event} $event By passing $event as argument, the corresponding event is stopped from propagating up the
+ * DOM-tree
+ *
+ * @description
+ * Opens the menu within the `md-menu` scope
+ */
+
 /**
- * Interim element provider for the menu.
- * Handles behavior for a menu while it is open, including:
- *    - handling animating the menu opening/closing
- *    - handling key/mouse events on the menu element
- *    - handling enabling/disabling scroll while the menu is open
- *    - handling redrawing during resizes and orientation changes
+ * @ngdoc method
+ * @name $mdMenu#close
  *
+ * @description
+ * Closes the menu within the `md-menu` scope
  */
 
 function MenuProvider($$interimElementProvider) {