From f05f5485460125ca6cea8d89170d1cef0edbb6fc Mon Sep 17 00:00:00 2001
From: Martin Staffa <mjstaffa@gmail.com>
Date: Thu, 5 Oct 2017 12:17:18 +0200
Subject: [PATCH 1/2] chore(doc-gen): improve headings for events and examples

The "Events" heading now gets an id (which makes them show in
the table of contents, and their "Parameters" use a heading with
a lower priority (previously it was the same as "Events" itself).

The "@example" tag now generates the heading "Example" if there's
only one, or "Examples" if there are multiple.
---
 docs/config/templates/ngdoc/api/api.template.html     | 2 +-
 docs/config/templates/ngdoc/lib/events.template.html  | 6 +++---
 docs/config/templates/ngdoc/lib/methods.template.html | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/config/templates/ngdoc/api/api.template.html b/docs/config/templates/ngdoc/api/api.template.html
index aa28ffa056ab..0a622197b4e2 100644
--- a/docs/config/templates/ngdoc/api/api.template.html
+++ b/docs/config/templates/ngdoc/api/api.template.html
@@ -52,7 +52,7 @@ <h2 id="dependencies">Dependencies</h2>
 
   {% block examples %}
   {%- if doc.examples %}
-  <h2 id="example">Examples</h2>
+  <h2 id="examples">{$ "Examples" if doc.examples | length > 1 else "Example" $}</h2>
   {%- for example in doc.examples -%}
     {$ example | marked $}
   {%- endfor -%}
diff --git a/docs/config/templates/ngdoc/lib/events.template.html b/docs/config/templates/ngdoc/lib/events.template.html
index 962c315dc888..b4b159de5008 100644
--- a/docs/config/templates/ngdoc/lib/events.template.html
+++ b/docs/config/templates/ngdoc/lib/events.template.html
@@ -2,11 +2,11 @@
 {% import "lib/deprecated.html" as x -%}
 
 {%- if doc.events %}
-<h2>Events</h2>
+<h2 id="events">Events</h2>
 <ul class="events">
   {%- for event in doc.events %}
   <li id="{$ event.name $}">
-    <h3>{$ event.name $}</h3>
+    <h3 id="event-{$ event.name $}">{$ event.name $}</h3>
     <div>{$ event.description | marked $}</div>
 
     {$ x.deprecatedBlock(event) $}
@@ -27,7 +27,7 @@ <h4>Target:</h4>
     {% endif -%}
     {%- if event.params %}
     <section class="api-section">
-      <h3>Parameters</h3>
+      <h4>Parameters</h4>
       {$ lib.paramTable(event.params) $}
     </section>
     {%- endif -%}
diff --git a/docs/config/templates/ngdoc/lib/methods.template.html b/docs/config/templates/ngdoc/lib/methods.template.html
index 8314ff3c76e1..9f449f97cfba 100644
--- a/docs/config/templates/ngdoc/lib/methods.template.html
+++ b/docs/config/templates/ngdoc/lib/methods.template.html
@@ -27,7 +27,7 @@ <h4>Returns</h4>
     {% endif %}
 
     {%- if method.examples %}
-    <h4 id="{$ doc.name $}.{$ method.name $}-examples">Examples</h4>
+    <h4 id="{$ doc.name $}.{$ method.name $}-examples">{$ "Examples" if method.examples | length > 1 else "Example" $}</h4>
     {%- for example in method.examples -%}
       {$ example | marked $}
     {%- endfor -%}

From e5c6174839e96113c93913dd8b3c4cca760dfc41 Mon Sep 17 00:00:00 2001
From: Martin Staffa <mjstaffa@gmail.com>
Date: Thu, 5 Oct 2017 12:17:55 +0200
Subject: [PATCH 2/2] docs(*): fix heading levels; use @example instead of
 headings

This ensures the doc-gen creates correct headlines and
table of contents entries.
---
 src/auto/injector.js              |  9 ++++-----
 src/ng/directive/ngModel.js       |  4 ++--
 src/ng/directive/ngNonBindable.js | 28 +++++++++++++---------------
 src/ng/directive/ngRepeat.js      |  8 ++++----
 src/ng/directive/select.js        |  5 ++++-
 src/ng/rootScope.js               |  8 ++++----
 src/ngAnimate/animateCss.js       |  2 +-
 src/ngMock/angular-mocks.js       |  2 +-
 src/ngRoute/route.js              |  4 ++--
 9 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/src/auto/injector.js b/src/auto/injector.js
index 19cefc807b49..f41d1e8c8e9a 100644
--- a/src/auto/injector.js
+++ b/src/auto/injector.js
@@ -264,7 +264,7 @@ function annotate(fn, strictDi, name) {
  * function is invoked. There are three ways in which the function can be annotated with the needed
  * dependencies.
  *
- * ## Argument names
+ * #### Argument names
  *
  * The simplest form is to extract the dependencies from the arguments of the function. This is done
  * by converting the function into a string using `toString()` method and extracting the argument
@@ -284,7 +284,7 @@ function annotate(fn, strictDi, name) {
  * This method does not work with code minification / obfuscation. For this reason the following
  * annotation strategies are supported.
  *
- * ## The `$inject` property
+ * #### The `$inject` property
  *
  * If a function has an `$inject` property and its value is an array of strings, then the strings
  * represent names of services to be injected into the function.
@@ -300,7 +300,7 @@ function annotate(fn, strictDi, name) {
  *   expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);
  * ```
  *
- * ## The array notation
+ * #### The array notation
  *
  * It is often desirable to inline Injected functions and that's when setting the `$inject` property
  * is very inconvenient. In these situations using the array notation to specify the dependencies in
@@ -360,8 +360,7 @@ function annotate(fn, strictDi, name) {
  * You can use {@link $injector#modules `$injector.modules`} to check whether a module has been loaded
  * into the injector, which may indicate whether the script has been executed already.
  *
- * ## Example
- *
+ * @example
  * Here is an example of loading a bundle of modules, with a utility method called `getScript`:
  *
  * ```javascript
diff --git a/src/ng/directive/ngModel.js b/src/ng/directive/ngModel.js
index b691e2959065..d7e95b49ed17 100644
--- a/src/ng/directive/ngModel.js
+++ b/src/ng/directive/ngModel.js
@@ -472,6 +472,7 @@ NgModelController.prototype = {
    * input which may have such events pending. This is important in order to make sure that the
    * input field will be updated with the new model value and any pending operations are cancelled.
    *
+   * @example
    * <example name="ng-model-cancel-update" module="cancel-update-example">
    *   <file name="app.js">
    *     angular.module('cancel-update-example', [])
@@ -906,8 +907,7 @@ NgModelController.prototype = {
    * This function can be used when the `$viewValue` or the rendered DOM value are not correctly
    * formatted and the `$modelValue` must be run through the `$formatters` again.
    *
-   * #### Example
-   *
+   * @example
    * Consider a text input with an autocomplete list (for fruit), where the items are
    * objects with a name and an id.
    * A user enters `ap` and then selects `Apricot` from the list.
diff --git a/src/ng/directive/ngNonBindable.js b/src/ng/directive/ngNonBindable.js
index 63fc2773e6c1..cab3db9bd648 100644
--- a/src/ng/directive/ngNonBindable.js
+++ b/src/ng/directive/ngNonBindable.js
@@ -5,6 +5,7 @@
  * @name ngNonBindable
  * @restrict AC
  * @priority 1000
+ * @element ANY
  *
  * @description
  * The `ngNonBindable` directive tells AngularJS not to compile or bind the contents of the current
@@ -12,24 +13,21 @@
  * bindings but which should be ignored by AngularJS. This could be the case if you have a site that
  * displays snippets of code, for instance.
  *
- * @element ANY
- *
  * @example
  * In this example there are two locations where a simple interpolation binding (`{{}}`) is present,
  * but the one wrapped in `ngNonBindable` is left alone.
  *
- * @example
-    <example name="ng-non-bindable">
-      <file name="index.html">
-        <div>Normal: {{1 + 2}}</div>
-        <div ng-non-bindable>Ignored: {{1 + 2}}</div>
-      </file>
-      <file name="protractor.js" type="protractor">
-       it('should check ng-non-bindable', function() {
-         expect(element(by.binding('1 + 2')).getText()).toContain('3');
-         expect(element.all(by.css('div')).last().getText()).toMatch(/1 \+ 2/);
-       });
-      </file>
-    </example>
+  <example name="ng-non-bindable">
+    <file name="index.html">
+      <div>Normal: {{1 + 2}}</div>
+      <div ng-non-bindable>Ignored: {{1 + 2}}</div>
+    </file>
+    <file name="protractor.js" type="protractor">
+     it('should check ng-non-bindable', function() {
+       expect(element(by.binding('1 + 2')).getText()).toContain('3');
+       expect(element.all(by.css('div')).last().getText()).toMatch(/1 \+ 2/);
+     });
+    </file>
+  </example>
  */
 var ngNonBindableDirective = ngDirective({ terminal: true, priority: 1000 });
diff --git a/src/ng/directive/ngRepeat.js b/src/ng/directive/ngRepeat.js
index ea32162a0c9c..ca80f386c991 100644
--- a/src/ng/directive/ngRepeat.js
+++ b/src/ng/directive/ngRepeat.js
@@ -30,7 +30,7 @@
  * </div>
  *
  *
- * # Iterating over object properties
+ * ## Iterating over object properties
  *
  * It is possible to get `ngRepeat` to iterate over the properties of an object using the following
  * syntax:
@@ -60,7 +60,7 @@
  * or implement a `$watch` on the object yourself.
  *
  *
- * # Tracking and Duplicates
+ * ## Tracking and Duplicates
  *
  * `ngRepeat` uses {@link $rootScope.Scope#$watchCollection $watchCollection} to detect changes in
  * the collection. When a change happens, `ngRepeat` then makes the corresponding changes to the DOM:
@@ -140,7 +140,7 @@
  * ```
  *
  *
- * # Special repeat start and end points
+ * ## Special repeat start and end points
  * To repeat a series of elements instead of just one parent element, ngRepeat (as well as other ng directives) supports extending
  * the range of the repeater by defining explicit start and end points by using **ng-repeat-start** and **ng-repeat-end** respectively.
  * The **ng-repeat-start** directive works the same as **ng-repeat**, but will repeat all the HTML code (including the tag it's defined on)
@@ -249,7 +249,7 @@
  * @example
  * This example uses `ngRepeat` to display a list of people. A filter is used to restrict the displayed
  * results by name or by age. New (entering) and removed (leaving) items are animated.
-  <example module="ngRepeat" name="ngRepeat" deps="angular-animate.js" animations="true" name="ng-repeat">
+  <example module="ngRepeat" name="ngRepeat" deps="angular-animate.js" animations="true">
     <file name="index.html">
       <div ng-controller="repeatController">
         I have {{friends.length}} friends. They are:
diff --git a/src/ng/directive/select.js b/src/ng/directive/select.js
index 7b8e5b4a47d2..5ae301844905 100644
--- a/src/ng/directive/select.js
+++ b/src/ng/directive/select.js
@@ -600,6 +600,7 @@ var SelectController =
  * </file>
  *</example>
  *
+ * @example
  * ### Using `ngRepeat` to generate `select` options
  * <example name="select-ngrepeat" module="ngrepeatSelect">
  * <file name="index.html">
@@ -629,6 +630,7 @@ var SelectController =
  * </file>
  *</example>
  *
+ * @example
  * ### Using `ngValue` to bind the model to an array of objects
  * <example name="select-ngvalue" module="ngvalueSelect">
  * <file name="index.html">
@@ -661,6 +663,7 @@ var SelectController =
  * </file>
  *</example>
  *
+ * @example
  * ### Using `select` with `ngOptions` and setting a default value
  * See the {@link ngOptions ngOptions documentation} for more `ngOptions` usage examples.
  *
@@ -692,7 +695,7 @@ var SelectController =
  * </file>
  *</example>
  *
- *
+ * @example
  * ### Binding `select` to a non-string value via `ngModel` parsing / formatting
  *
  * <example name="select-with-non-string-options" module="nonStringSelect">
diff --git a/src/ng/rootScope.js b/src/ng/rootScope.js
index 60567c0aa065..e293b7f4e483 100644
--- a/src/ng/rootScope.js
+++ b/src/ng/rootScope.js
@@ -318,7 +318,7 @@ function $RootScopeProvider() {
        *
        *
        *
-       * #### Example
+       * @example
        * ```js
            // let's assume that scope was dependency injected as the $rootScope
            var scope = $rootScope;
@@ -541,7 +541,7 @@ function $RootScopeProvider() {
        *   adding, removing, and moving items belonging to an object or array.
        *
        *
-       * #### Example
+       * @example
        * ```js
           $scope.names = ['igor', 'matias', 'misko', 'james'];
           $scope.dataCount = 4;
@@ -743,7 +743,7 @@ function $RootScopeProvider() {
        *
        * In unit tests, you may need to call `$digest()` to simulate the scope life cycle.
        *
-       * #### Example
+       * @example
        * ```js
            var scope = ...;
            scope.name = 'misko';
@@ -972,7 +972,7 @@ function $RootScopeProvider() {
        * the expression are propagated (uncaught). This is useful when evaluating AngularJS
        * expressions.
        *
-       * #### Example
+       * @example
        * ```js
            var scope = ng.$rootScope.Scope();
            scope.a = 1;
diff --git a/src/ngAnimate/animateCss.js b/src/ngAnimate/animateCss.js
index b64cda7e0afe..75c9270ab4d0 100644
--- a/src/ngAnimate/animateCss.js
+++ b/src/ngAnimate/animateCss.js
@@ -18,7 +18,7 @@ var ANIMATE_TIMER_KEY = '$$animateCss';
  * Note that only browsers that support CSS transitions and/or keyframe animations are capable of
  * rendering animations triggered via `$animateCss` (bad news for IE9 and lower).
  *
- * ## Usage
+ * ## General Use
  * Once again, `$animateCss` is designed to be used inside of a registered JavaScript animation that
  * is powered by ngAnimate. It is possible to use `$animateCss` directly inside of a directive, however,
  * any automatic control over cancelling animations and/or preventing animations from being run on
diff --git a/src/ngMock/angular-mocks.js b/src/ngMock/angular-mocks.js
index eb5da0816d38..8ee32d27a955 100644
--- a/src/ngMock/angular-mocks.js
+++ b/src/ngMock/angular-mocks.js
@@ -2472,7 +2472,7 @@ angular.module('ngMockE2E', ['ng']).config(['$provide', function($provide) {
  *
  * Afterwards, bootstrap your app with this new module.
  *
- * ## Example
+ * @example
  * <example name="httpbackend-e2e-testing" module="myAppE2E" deps="angular-mocks.js">
  * <file name="app.js">
  *   var myApp = angular.module('myApp', []);
diff --git a/src/ngRoute/route.js b/src/ngRoute/route.js
index 49113092d6ff..76f915b97da6 100644
--- a/src/ngRoute/route.js
+++ b/src/ngRoute/route.js
@@ -17,7 +17,7 @@ var noop;
  * The `ngRoute` module provides routing and deeplinking services and directives for AngularJS apps.
  *
  * ## Example
- * See {@link ngRoute.$route#example $route} for an example of configuring and using `ngRoute`.
+ * See {@link ngRoute.$route#examples $route} for an example of configuring and using `ngRoute`.
  *
  */
 /* global -ngRouteModule */
@@ -43,7 +43,7 @@ var isEagerInstantiationEnabled;
  * Used for configuring routes.
  *
  * ## Example
- * See {@link ngRoute.$route#example $route} for an example of configuring and using `ngRoute`.
+ * See {@link ngRoute.$route#examples $route} for an example of configuring and using `ngRoute`.
  *
  * ## Dependencies
  * Requires the {@link ngRoute `ngRoute`} module to be installed.