docs(interimElement): improve documentation

- improves comments and JSDoc
- this service is still hidden on our docs site though

src/core/services/interimElement/interimElement.js

@@ -1,10 +1,10 @@
 angular.module('material.core')
   .provider('$$interimElement', InterimElementProvider);
 
-/*
+/**
  * @ngdoc service
- * @name $$interimElement
- * @module material.core
+ * @name $$interimElementProvider
+ * @module material.core.interimElement
  *
  * @description
  *
@@ -13,16 +13,16 @@ angular.module('material.core')
  * The service provides a promise-like API for interacting with the temporary
  * elements.
  *
- * ```js
- * app.service('$mdToast', function($$interimElement) {
- *   var $mdToast = $$interimElement(toastDefaultOptions);
- *   return $mdToast;
- * });
- * ```
+ * <hljs lang="js">
+ *   app.service('$mdToast', function($$interimElement) {
+ *     var $mdToast = $$interimElement(toastDefaultOptions);
+ *     return $mdToast;
+ *   });
+ * </hljs>
+ *
  * @param {object=} defaultOptions Options used by default for the `show` method on the service.
  *
  * @returns {$$interimElement.$service}
- *
  */
 
 function InterimElementProvider() {
@@ -71,7 +71,6 @@ function InterimElementProvider() {
     /**
      * Add a method to the factory that isn't specific to any interim element operations
      */
-
     function addMethod(name, fn) {
       customMethods[name] = fn;
       return provider;
@@ -238,9 +237,7 @@ function InterimElementProvider() {
         locals[interimFactoryName] = publicService;
         return $injector.invoke(factory || function() { return defaultVal; }, {}, locals);
       }
-
     }
-
   }
 
   /* @ngInject */
@@ -249,24 +246,21 @@ function InterimElementProvider() {
     return function createInterimElementService() {
       var SHOW_CANCELLED = false;
 
-      /*
+      /**
        * @ngdoc service
-       * @name $$interimElement.$service
+       * @name $$interimElementProvider.$service
        *
        * @description
-       * A service used to control inserting and removing an element into the DOM.
-       *
+       * A service used to control inserting and removing of an element from the DOM.
+       * It is used by $mdBottomSheet, $mdDialog, $mdToast, $mdMenu, $mdPanel, and $mdSelect.
        */
-
       var service;
 
       var showPromises = []; // Promises for the interim's which are currently opening.
       var hidePromises = []; // Promises for the interim's which are currently hiding.
       var showingInterims = []; // Interim elements which are currently showing up.
 
       // Publish instance $$interimElement service;
-      // ... used as $mdDialog, $mdToast, $mdMenu, and $mdSelect
-
       return service = {
         show: show,
         hide: waitForInterim(hide),
@@ -275,18 +269,18 @@ function InterimElementProvider() {
         $injector_: $injector
       };
 
-      /*
+      /**
        * @ngdoc method
-       * @name $$interimElement.$service#show
+       * @name $$interimElementProvider.$service#show
        * @kind function
        *
        * @description
-       * Adds the `$interimElement` to the DOM and returns a special promise that will be resolved or rejected
-       * with hide or cancel, respectively. To external cancel/hide, developers should use the
-       *
-       * @param {*} options is hashMap of settings
-       * @returns a Promise
+       * Adds the `$interimElement` to the DOM and returns a special promise that will be resolved
+       * or rejected with hide or cancel, respectively.
        *
+       * @param {object} options map of options and values
+       * @returns {Promise} a Promise that will be resolved when hide() is called or rejected when
+       *  cancel() is called.
        */
       function show(options) {
         options = options || {};
@@ -341,15 +335,16 @@ function InterimElementProvider() {
 
       /**
        * @ngdoc method
-       * @name $$interimElement.$service#hide
+       * @name $$interimElementProvider.$service#hide
        * @kind function
        *
        * @description
-       * Removes the `$interimElement` from the DOM and resolves the promise returned from `show`.
+       * Removes the `$interimElement` from the DOM and resolves the Promise returned from `show()`.
        *
-       * @param {*} reason Data to resolve the promise with
-       * @param {object} options
-       * @returns {Promise} a Promise that will be resolved after the element has been removed.
+       * @param {*} reason Data used to resolve the Promise
+       * @param {object} options map of options and values
+       * @returns {Promise} a Promise that will be resolved after the element has been removed
+       *  from the DOM.
        */
       function hide(reason, options) {
         options = options || {};
@@ -389,15 +384,16 @@ function InterimElementProvider() {
 
       /**
        * @ngdoc method
-       * @name $$interimElement.$service#cancel
+       * @name $$interimElementProvider.$service#cancel
        * @kind function
        *
        * @description
-       * Removes the `$interimElement` from the DOM and rejects the promise returned from `show`
+       * Removes the `$interimElement` from the DOM and rejects the Promise returned from `show()`.
        *
-       * @param {*} reason Data to reject the promise with
-       * @param {object} options
-       * @returns {Promise} Promise that will be resolved after the element has been removed.
+       * @param {*} reason Data used to resolve the Promise
+       * @param {object} options map of options and values
+       * @returns {Promise} Promise that will be resolved after the element has been removed
+       *  from the DOM.
        */
       function cancel(reason, options) {
         var interim = showingInterims.pop();
@@ -445,9 +441,15 @@ function InterimElementProvider() {
         };
       }
 
-      /*
-       * Special method to quick-remove the interim element without animations
-       * Note: interim elements are in "interim containers"
+      /**
+       * @ngdoc method
+       * @name $$interimElementProvider.$service#destroy
+       * @kind function
+       *
+       * Special method to quick-remove the interim element without running animations. This is
+       * useful when the parent component has been or is being destroyed.
+       *
+       * Note: interim elements are in "interim containers".
        */
       function destroy(targetEl) {
         var interim = !targetEl ? showingInterims.shift() : null;
@@ -758,7 +760,5 @@ function InterimElementProvider() {
 
       }
     };
-
   }
-
 }