From 730a33b9c34babaa7f4c861fa172935eaabea740 Mon Sep 17 00:00:00 2001
From: Andy Joslin <andytjoslin@gmail.com>
Date: Fri, 11 Apr 2014 09:06:54 -0600
Subject: [PATCH] feat($ionicBackdrop): add backdrop show/hide service

Closes #1084
---
 docs/templates/api_menu_version.template.html | 14 +++++-
 js/ext/angular/src/service/ionicBackdrop.js   | 44 ++++++++++++++++++-
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/docs/templates/api_menu_version.template.html b/docs/templates/api_menu_version.template.html
index a75a48191c..9fa3148b02 100644
--- a/docs/templates/api_menu_version.template.html
+++ b/docs/templates/api_menu_version.template.html
@@ -399,7 +399,19 @@
     </ul>
   </li>
 
-
+  <!-- Backdrop -->
+  <li class="menu-section">
+    <a href="#" class="api-section">
+      Backdrop
+    </a>
+    <ul>
+      <li>
+        <a href="{{ page.versionHref }}/api/service/$ionicBackdrop">
+          $ionicBackdrop
+        </a>
+      </li>
+    </ul>
+  </li>
 
   <!-- Utility -->
   <li class="menu-section">
diff --git a/js/ext/angular/src/service/ionicBackdrop.js b/js/ext/angular/src/service/ionicBackdrop.js
index 920865acc0..c9c3b6d6c5 100644
--- a/js/ext/angular/src/service/ionicBackdrop.js
+++ b/js/ext/angular/src/service/ionicBackdrop.js
@@ -1,7 +1,38 @@
 angular.module('ionic')
 
 /**
- * @private
+ * @ngdoc service
+ * @name $ionicBackdrop
+ * @module ionic
+ * @description
+ * Shows and hides a backdrop over the UI.  Appears behind popups, loading,
+ * and other overlays.
+ *
+ * Often, multiple UI components require a backdrop, but only one backdrop is
+ * ever needed in the DOM at a time.
+ *
+ * Therefore, each component that requires the backdrop to be shown calls
+ * `$ionicBackdrop.retain()` when it wants the backdrop, then `$ionicBackdrop.release()`
+ * when it is done with the backdrop.
+ *
+ * For each time `retain` is called, the backdrop will be shown until `release` is called.
+ *
+ * For example, if `retain` is called three times, the backdrop will be shown until `release` 
+ * is called three times.
+ *
+ * @usage
+ *
+ * ```js
+ * function MyController($scope, $ionicBackdrop, $timeout) {
+ *   //Show a backdrop for one second
+ *   $scope.action = function() {
+ *     $ionicBackdrop.retain();
+ *     $timeout(function() {
+ *       $ionicBackdrop.release();
+ *     }, 1000);
+ *   };
+ * }
+ * ```
  */
 .factory('$ionicBackdrop', [
   '$document',
@@ -13,7 +44,18 @@ function($document) {
   $document[0].body.appendChild(el[0]);
 
   return {
+    /**
+     * @ngdoc method
+     * @name $ionicBackdrop#retain
+     * @description Retains the backdrop.
+     */
     retain: retain,
+    /**
+     * @ngdoc method
+     * @name $ionicBackdrop#retain
+     * @description
+     * Releases the backdrop.
+     */
     release: release,
     // exposed for testing
     _element: el