docs(popover): tune up

Closes angular-ui#5146

src/popover/docs/demo.html

@@ -42,4 +42,5 @@ <h4>Triggers</h4>
     <h4>Other</h4>
     <button popover-animation="true" uib-popover="I fade in and out!" type="button" class="btn btn-default">fading</button>
     <button uib-popover="I have a title!" popover-title="The title." type="button" class="btn btn-default">title</button>
+    <button uib-popover="I am activated manually" popover-is-open="popoverIsOpen" ng-click="popoverIsOpen = !popoverIsOpen" type="button" class="btn btn-default">Toggle popover</button>
 </div>

src/popover/docs/readme.md

@@ -4,55 +4,104 @@ directive supports multiple placements, optional transition animation, and more.
 Like the Bootstrap jQuery plugin, the popover **requires** the tooltip
 module.
 
-There are two versions of the popover: `uib-popover` and `uib-popover-template`:
-
-- `uib-popover` takes text only and will escape any HTML provided for the popover
-  body.
-- `uib-popover-html` takes an expression that evaluates to an html string. *The user is responsible for ensuring the
-  content is safe to put into the DOM!*
-- `uib-popover-template` a URL representing the location of a template to
-  use for the popover body. Note that the contents of this template need to be
-  wrapped in a tag, e.g., `<div></div>`.
-
-The popover directives provides several optional attributes to control how it
-will display:
-
-- `popover-title`: A string to display as a fancy title.
-- `popover-placement`: Where to place it? Defaults to "top". Passing in 'auto' seperated by a space before the placement will
-  enable auto positioning, e.g: "auto bottom-left". The popover will attempt to position where it fits in
-  the closest scrollable ancestor. Accepts:
-
-   - "top" - popover on top, horizontally centered on host element.
-   - "top-left" - popover on top, left edge aligned with host element left edge.
-   - "top-right" - popover on top, right edge aligned with host element right edge.
-   - "bottom" - popover on bottom, horizontally centered on host element.
-   - "bottom-left" - popover on bottom, left edge aligned with host element left edge.
-   - "bottom-right" - popover on bottom, right edge aligned with host element right edge.
-   - "left" - popover on left, vertically centered on host element.
-   - "left-top" - popover on left, top edge aligned with host element top edge.
-   - "left-bottom" - popover on left, bottom edge aligned with host element bottom edge.
-   - "right" - popover on right, vertically centered on host element.
-   - "right-top" - popover on right, top edge aligned with host element top edge.
-   - "right-bottom" - popover on right, bottom edge aligned with host element bottom edge.
-- `popover-animation`: Should it fade in and out? Defaults to "true".
-- `popover-popup-delay`: For how long should the user have to have the mouse
-  over the element before the popover shows (in milliseconds)? Defaults to 0.
-- `popover-popup-close-delay`: For how long should the popover remain open
-  after the close trigger event? Defaults to 0.
-- `popover-trigger`: What should trigger the show of the popover? See the
-  `tooltip` directive for supported values.
-- `popover-append-to-body`_(Default: false)_: Should the popover be appended to `$body` instead of
-  the parent element?
-- `popover-is-open` <i class="glyphicon glyphicon-eye-open"></i>
-  _(Default: false)_:
+There are three versions of the popover: `uib-popover` and `uib-popover-template`, and `uib-tooltip-html`:
+
+* `uib-popover`
+  Takes text only and will escape any HTML provided for the popover body.
+
+* `uib-popover-html`
+  Takes an expression that evaluates to an html string. *The user is responsible for ensuring the content is safe to put into the DOM!*
+
+* `uib-popover-template`
+  A URL representing the location of a template to use for the popover body. Note that the contents of this template need to be wrapped in a tag, e.g., `<div></div>`.
+
+### uib-popover-* settings
+
+All these settings are available for the three types of popovers.
+
+* `popover-animation`
+  <small class="badge">$</small>
+  <small class="badge">C</small>
+  _(Default: `true`, Config: `animation`)_ -
+  Should it fade in and out?
+
+* `popover-append-to-body`
+  <small class="badge">$</small>
+  _(Default: `false`)_ -
+  Should the popover be appended to '$body' instead of the parent element?
+
+* `popover-is-open`
+  <i class="glyphicon glyphicon-eye-open"></i>
+  _(Default: `false`)_ -
   Whether to show the popover.
 
-The popover directives require the `$position` service.
+* `popover-placement`
+  <small class="badge">C</small>
+  _(Default: `top`, Config: `placement`)_ -
+  Passing in 'auto' separated by a space before the placement will enable auto positioning, e.g: "auto bottom-left". The popover will attempt to position where it fits in the closest scrollable ancestor. Accepts:
+
+   * `top` - popover on top, horizontally centered on host element.
+   * `top-left` - popover on top, left edge aligned with host element left edge.
+   * `top-right` - popover on top, right edge aligned with host element right edge.
+   * `bottom` - popover on bottom, horizontally centered on host element.
+   * `bottom-left` - popover on bottom, left edge aligned with host element left edge.
+   * `bottom-right` - popover on bottom, right edge aligned with host element right edge.
+   * `left` - popover on left, vertically centered on host element.
+   * `left-top` - popover on left, top edge aligned with host element top edge.
+   * `left-bottom` - popover on left, bottom edge aligned with host element bottom edge.
+   * `right` - popover on right, vertically centered on host element.
+   * `right-top` - popover on right, top edge aligned with host element top edge.
+   * `right-bottom` - popover on right, bottom edge aligned with host element bottom edge.
+
+* `popover-popup-close-delay`
+  <small class="badge">C</small>
+  _(Default: `0`, Config: `popupCloseDelay`)_ -
+  For how long should the popover remain open after the close trigger event?
+
+* `popover-popup-delay`
+  <small class="badge">C</small>
+  _(Default: `0`, Config: `popupDelay`)_ -
+  Popup delay in milliseconds until it opens.
+
+* `popover-title` -
+   A string to display as a fancy title.
+
+* `popover-trigger`
+  _(Default: `mouseenter`)_ -
+  What should trigger a show of the popover? Supports a space separated list of event names (see below).
+
+**Note:** To configure the tooltips, you need to do it on `$uibTooltipProvider` (also see below).
+
+### Triggers
+
+The following show triggers are supported out of the box, along with their provided hide triggers:
+
+- `mouseenter`: `mouseleave`
+- `click`: `click`
+- `outsideClick`: `outsideClick`
+- `focus`: `blur`
+- `none`
+
+The `outsideClick` trigger will cause the popover to toggle on click, and hide when anything else is clicked.
+
+For any non-supported value, the trigger will be used to both show and hide the
+popover. Using the 'none' trigger will disable the internal trigger(s), one can
+then use the `popover-is-open` attribute exclusively to show and hide the popover.
+
+### $uibTooltipProvider
+
+Through the `$uibTooltipProvider`, you can change the way tooltips and popovers
+behave by default; the attributes above always take precedence. The following
+methods are available:
 
-The popover directive also supports various default configurations through the
-$tooltipProvider. See the [tooltip](#tooltip) section for more information.
+* `setTriggers(obj)`
+  _(Example: `{ 'openTrigger': 'closeTrigger' }`)_ -
+  Extends the default trigger mappings mentioned above with mappings of your own.
+
+* `options(obj)` -
+  Provide a set of defaults for certain tooltip and popover attributes. Currently supports the ones with the <small class="badge">C</small> badge.
 
-**Known issues**
+### Known issues
 
 For Safari 7+ support, if you want to use **focus** `popover-trigger`, you need to use an anchor tag with a tab index. For example: