From 42b0b63a28a9bbcf5331096bd877ef56a94f8899 Mon Sep 17 00:00:00 2001
From: Adam Bradley <adambradley25@gmail.com>
Date: Thu, 31 Jul 2014 16:09:42 -0500
Subject: [PATCH] docs(popover): $ionicPopover / ionicPopover

---
 .../templates/api_menu_version.template.html  | 36 ++++++++
 js/angular/service/popover.js                 | 89 ++++++++++++++++---
 js/angular/service/position.js                |  8 +-
 3 files changed, 116 insertions(+), 17 deletions(-)

diff --git a/config/docs/templates/api_menu_version.template.html b/config/docs/templates/api_menu_version.template.html
index b4adc1b468..7faf822af0 100644
--- a/config/docs/templates/api_menu_version.template.html
+++ b/config/docs/templates/api_menu_version.template.html
@@ -318,6 +318,27 @@
   </li>
 
 
+  <!-- Popover -->
+  <li class="menu-section">
+    <a href="#" class="api-section">
+       Popover
+    </a>
+    <ul>
+      <li>
+        <a href="{{ page.versionHref }}/api/service/$ionicPopover/">
+          $ionicPopover
+        </a>
+      </li>
+
+      <li>
+        <a href="{{ page.versionHref }}/api/controller/ionicPopover/">
+          ionicPopover
+        </a>
+      </li>
+    </ul>
+  </li>
+
+
   <!-- Action Sheet -->
   <li class="menu-section">
     <a href="#" class="api-section">
@@ -495,6 +516,21 @@
   </li>
 
 
+  <!-- Position -->
+  <li class="menu-section">
+    <a href="#" class="api-section">
+      Position
+    </a>
+    <ul>
+      <li>
+        <a href="{{ page.versionHref }}/api/service/$ionicPosition/">
+          $ionicPosition
+        </a>
+      </li>
+    </ul>
+  </li>
+
+
   <!-- Utility -->
   <li class="menu-section">
     <a href="#" class="api-section">
diff --git a/js/angular/service/popover.js b/js/angular/service/popover.js
index 3043d2399c..05f5d39cd9 100644
--- a/js/angular/service/popover.js
+++ b/js/angular/service/popover.js
@@ -4,6 +4,8 @@
  * @module ionic
  * @description
  *
+ * Related: {@link ionic.controller:ionicPopover ionicPopover controller}.
+ *
  * The Popover is a view that floats above an app’s content. Popovers provide an
  * easy way to present or gather information from the user and are
  * commonly used in the following situations:
@@ -14,12 +16,12 @@
  *
  * Put the content of the popover inside of an `<ion-popover-view>` element.
  *
- * Note: a popover will broadcast 'popover.shown', 'popover.hidden', and 'popover.removed' events from its originating
- * scope, passing in itself as an event argument. Both the popover.removed and popover.hidden events are
- * called when the popover is removed.
- *
  * @usage
  * ```html
+ * <p>
+ *   <button ng-click="openPopover($event)">Open Popover</button>
+ * </p>
+ *
  * <script id="my-popover.html" type="text/ng-template">
  *   <ion-popover-view>
  *     <ion-header-bar>
@@ -39,8 +41,8 @@
  *   }).then(function(popover) {
  *     $scope.popover = popover;
  *   });
- *   $scope.openPopover = function() {
- *     $scope.popover.show();
+ *   $scope.openPopover = function($event) {
+ *     $scope.popover.show($event);
  *   };
  *   $scope.closePopover = function() {
  *     $scope.popover.hide();
@@ -60,9 +62,11 @@
  * });
  * ```
  */
+
+
 IonicModule
-.factory('$ionicPopover', ['$ionicModal', '$ionicPosition', '$document',
-function($ionicModal, $ionicPosition, $document) {
+.factory('$ionicPopover', ['$ionicPopover', '$ionicPosition', '$document',
+function($ionicPopover, $ionicPosition, $document) {
 
   var POPOVER_BODY_PADDING = 6;
 
@@ -105,6 +109,65 @@ function($ionicModal, $ionicPosition, $document) {
 
   }
 
+  /**
+   * @ngdoc controller
+   * @name ionicPopover
+   * @module ionic
+   * @description
+   * Instantiated by the {@link ionic.service:$ionicPopover} service.
+   *
+   * Be sure to call [remove()](#remove) when you are done with each popover
+   * to clean it up and avoid memory leaks.
+   *
+   * Note: a popover will broadcast 'popover.shown', 'popover.hidden', and 'popover.removed' events from its originating
+   * scope, passing in itself as an event argument. Both the popover.removed and popover.hidden events are
+   * called when the popover is removed.
+   */
+
+  /**
+   * @ngdoc method
+   * @name ionicPopover#initialize
+   * @description Creates a new popover controller instance.
+   * @param {object} options An options object with the following properties:
+   *  - `{object=}` `scope` The scope to be a child of.
+   *    Default: creates a child of $rootScope.
+   *  - `{boolean=}` `focusFirstInput` Whether to autofocus the first input of
+   *    the popover when shown.  Default: false.
+   *  - `{boolean=}` `backdropClickToClose` Whether to close the popover on clicking the backdrop.
+   *    Default: true.
+   *  - `{boolean=}` `hardwareBackButtonClose` Whether the popover can be closed using the hardware
+   *    back button on Android and similar devices.  Default: true.
+   */
+
+  /**
+   * @ngdoc method
+   * @name ionicPopover#show
+   * @description Show this popover instance.
+   * @param {$event} $event The $event or target element which the popover should align
+   * itself next to.
+   * @returns {promise} A promise which is resolved when the popover is finished animating in.
+   */
+
+  /**
+   * @ngdoc method
+   * @name ionicPopover#hide
+   * @description Hide this popover instance.
+   * @returns {promise} A promise which is resolved when the popover is finished animating out.
+   */
+
+  /**
+   * @ngdoc method
+   * @name ionicPopover#remove
+   * @description Remove this popover instance from the DOM and clean up.
+   * @returns {promise} A promise which is resolved when the popover is finished animating out.
+   */
+
+  /**
+   * @ngdoc method
+   * @name ionicPopover#isShown
+   * @returns boolean Whether this popover is currently shown.
+   */
+
   return {
     /**
      * @ngdoc method
@@ -112,11 +175,11 @@ function($ionicModal, $ionicPosition, $document) {
      * @param {string} templateString The template string to use as the popovers's
      * content.
      * @param {object} options Options to be passed to the initialize method.
-     * @returns {object} An instance of an {@link ionic.controller:ionicModal}
-     * controller ($ionicPopover is built on top of $ionicModal).
+     * @returns {object} An instance of an {@link ionic.controller:ionicPopover}
+     * controller ($ionicPopover is built on top of $ionicPopover).
      */
     fromTemplate: function(templateString, options) {
-      return $ionicModal.fromTemplate(templateString, ionic.Utils.extend(options || {}, POPOVER_OPTIONS) );
+      return $ionicPopover.fromTemplate(templateString, ionic.Utils.extend(options || {}, POPOVER_OPTIONS) );
     },
     /**
      * @ngdoc method
@@ -124,10 +187,10 @@ function($ionicModal, $ionicPosition, $document) {
      * @param {string} templateUrl The url to load the template from.
      * @param {object} options Options to be passed to the initialize method.
      * @returns {promise} A promise that will be resolved with an instance of
-     * an {@link ionic.controller:ionicModal} controller ($ionicPopover is built on top of $ionicModal).
+     * an {@link ionic.controller:ionicPopover} controller ($ionicPopover is built on top of $ionicPopover).
      */
     fromTemplateUrl: function(url, options, _) {
-      return $ionicModal.fromTemplateUrl(url, options, ionic.Utils.extend(options || {}, POPOVER_OPTIONS) );
+      return $ionicPopover.fromTemplateUrl(url, options, ionic.Utils.extend(options || {}, POPOVER_OPTIONS) );
     }
   };
 
diff --git a/js/angular/service/position.js b/js/angular/service/position.js
index 56278f6bc6..0b6de8acfa 100644
--- a/js/angular/service/position.js
+++ b/js/angular/service/position.js
@@ -7,8 +7,8 @@
  * It is meant to be used where we need to absolute-position DOM elements in
  * relation to other, existing elements (this is the case for tooltips, popovers, etc.).
  *
- * Adapted from [ui.bootstrap.position](https://github.com/angular-ui/bootstrap/blob/master/src/position/position.js),
- * [License](https://github.com/angular-ui/bootstrap/blob/master/LICENSE)
+ * Adapted from [AngularUI Bootstrap](https://github.com/angular-ui/bootstrap/blob/master/src/position/position.js),
+ * ([license](https://github.com/angular-ui/bootstrap/blob/master/LICENSE))
  */
 IonicModule
 .factory('$ionicPosition', ['$document', '$window', function ($document, $window) {
@@ -49,7 +49,7 @@ IonicModule
      * @ngdoc method
      * @name $ionicPosition#position
      * @description Get the current coordinates of the element, relative to the offset parent.
-     * Read-only equivalent of [jQuery's position function](http://api.jquery.com/position/)
+     * Read-only equivalent of [jQuery's position function](http://api.jquery.com/position/).
      * @param {element} element The element to get the position of.
      * @returns {object} Returns an object containing the properties top, left, width and height.
      */
@@ -76,7 +76,7 @@ IonicModule
      * @ngdoc method
      * @name $ionicPosition#offset
      * @description Get the current coordinates of the element, relative to the document.
-     * Read-only equivalent of [jQuery's offset function](http://api.jquery.com/offset/)
+     * Read-only equivalent of [jQuery's offset function](http://api.jquery.com/offset/).
      * @param {element} element The element to get the offset of.
      * @returns {object} Returns an object containing the properties top, left, width and height.
      */