docs(*): fix heading levels and general clean-up

- docs pages should only have one h1
- docs pages shouldn't skip a h* in the hierarchy
- manual table of contents are no longer necesary
- references to the doc-module-components directive are obsolete

Author: Narretz

docs/config/templates/ngdoc/api/filter.template.html

@@ -2,7 +2,7 @@
 {% extends "api/api.template.html" %}
 
 {% block additional %}
-  <h2>Usage</h2>
+  <h2 id="usage">Usage</h2>
   <h3>In HTML Template Binding</h3>
   {% if doc.usage %}
     {$ doc.usage | code $}

docs/content/guide/directive.ngdoc

@@ -977,7 +977,7 @@ controllers using `require`.
 Otherwise use `link`.
 </div>
 
-### Summary
+## Summary
 
 Here we've seen the main use cases for directives. Each of these samples acts as a good starting
 point for creating your own directives.

docs/content/guide/migration.ngdoc

@@ -15,22 +15,6 @@ which drives many of these changes.
 * Several new features, especially animations, would not be possible without a few changes.
 * Finally, some outstanding bugs were best fixed by changing an existing API.
 
-
-
-## Contents
-
-<ul class="nav nav-list">
-  <li>{@link guide/migration#migrating-from-1-5-to-1-6 Migrating from 1.5 to 1.6}</li>
-  <li>{@link guide/migration#migrating-from-1-4-to-1-5 Migrating from 1.4 to 1.5}</li>
-  <li>{@link guide/migration#migrating-from-1-3-to-1-4 Migrating from 1.3 to 1.4}</li>
-  <li>{@link guide/migration#migrating-from-1-2-to-1-3 Migrating from 1.2 to 1.3}</li>
-  <li>{@link guide/migration#migrating-from-1-0-to-1-2 Migrating from 1.0 to 1.2}</li>
-</ul>
-
-
-
-
-
 ## Migrating from 1.5 to 1.6
 
 AngularJS 1.6 fixes numerous bugs and adds new features, both in core and in external modules.
@@ -1405,7 +1389,7 @@ always assumed to be of type 'string', so passing non-string values never worked
 The main difference is that now it will fail faster and with a more informative error message.
 
 
-## ngTouch (`ngClick`)
+### ngTouch (`ngClick`)
 
 Due to [0dfc1dfe](https://github.com/angular/angular.js/commit/0dfc1dfebf26af7f951f301c4e3848ac46f05d7f),
 the `ngClick` override directive from the `ngTouch` module is **deprecated and disabled by default**.
@@ -1567,7 +1551,7 @@ class based animations (animations triggered via ngClass) in order to ensure tha
 
 
 
-### Forms (`ngMessages`, `ngOptions`, `select`, `ngPattern` and `pattern`)
+### Forms (`ngMessages`, `ngOptions`, `select`, `ngPattern` and `pattern`, `form`)
 
 #### ngMessages
 The ngMessages module has also been subject to an internal refactor to allow it to be more flexible
@@ -1749,7 +1733,7 @@ the built-in pattern validator:
 ```
 
 
-### form
+#### form
 
 Due to [94533e57](https://github.com/angular/angular.js/commit/94533e570673e6b2eb92073955541fa289aabe02),
 the `name` attribute of `form` elements can now only contain characters that can be evaluated as part

docs/content/misc/contribute.ngdoc

@@ -10,14 +10,6 @@ explains the basic mechanics of using `git`, `node`, `yarn`, `grunt`, and `bower
 See the [contributing guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)
 for how to contribute your own code to AngularJS.
 
-
-1. {@link misc/contribute#installing-dependencies Installing Dependencies}
-2. {@link misc/contribute#forking-angularjs-on-github Forking AngularJS on Github}
-3. {@link misc/contribute#building-angularjs Building AngularJS}
-4. {@link misc/contribute#running-a-local-development-web-server Running a Local Development Web Server}
-5. {@link misc/contribute#running-the-unit-test-suite Running the Unit Test Suite}
-6. {@link misc/contribute#running-the-end-to-end-test-suite Running the End-to-end Test Suite}
-
 ## Installing Dependencies
 
 Before you can build AngularJS, you must install and configure the following dependencies on your

docs/content/misc/started.ngdoc

@@ -16,9 +16,9 @@ becoming an AngularJS expert.
    starter app with a directory layout, test harness, and scripts to begin building your application.
 
 
-# Further Steps
+## Further Steps
 
-## Watch Videos
+### Watch Videos
 
 If you haven’t had a chance to watch the videos from the homepage, please check out:
 
@@ -29,13 +29,13 @@ If you haven’t had a chance to watch the videos from the homepage, please chec
 And visit our [YouTube channel](http://www.youtube.com/user/angularjs) for more AngularJS video presentations and
 tutorials.
 
-## Subscribe
+### Subscribe
 
 * Subscribe to the [mailing list](http://groups.google.com/forum/?fromgroups#!forum/angular).  Ask questions here!
 * Follow us on [Twitter](https://twitter.com/intent/follow?original_referer=http%3A%2F%2Fangularjs.org%2F&region=follow_link&screen_name=angular&source=followbutton&variant=2.0)
 * Add us to your circles on [Google+](https://plus.google.com/110323587230527980117/posts)
 
-## Read more
+### Read more
 
 The AngularJS documentation includes the {@link guide/index Developer Guide} covering concepts and the
 {@link ./api API Reference} for syntax and usage.

src/Angular.js

@@ -112,13 +112,11 @@
  * @installation
  * @description
  *
- * # ng (core module)
  * The ng module is loaded by default when an AngularJS application is started. The module itself
  * contains the essential components for an AngularJS application to function. The table below
  * lists a high level breakdown of each of the services/factories, filters, directives and testing
  * components available within this core module.
  *
- * <div doc-module-components="ng"></div>
  */
 
 var REGEX_STRING_REGEXP = /^\/(.+)\/([a-z]*)$/;

src/auto/injector.js

@@ -147,7 +147,7 @@ function annotate(fn, strictDi, name) {
  *   })).toBe($injector);
  * ```
  *
- * # Injection Function Annotation
+ * ## Injection Function Annotation
  *
  * JavaScript does not have annotations, and annotations are needed for dependency injection. The
  * following are all valid ways of annotating function with injection arguments and are equivalent.
@@ -165,18 +165,18 @@ function annotate(fn, strictDi, name) {
  *   $injector.invoke(['serviceA', function(serviceA){}]);
  * ```
  *
- * ## Inference
+ * ### Inference
  *
  * In JavaScript calling `toString()` on a function returns the function definition. The definition
  * can then be parsed and the function arguments can be extracted. This method of discovering
  * annotations is disallowed when the injector is in strict mode.
  * *NOTE:* This does not work with minification, and obfuscation tools since these tools change the
  * argument names.
  *
- * ## `$inject` Annotation
+ * ### `$inject` Annotation
  * By adding an `$inject` property onto a function the injection parameters can be specified.
  *
- * ## Inline
+ * ### Inline
  * As an array of injection names, where the last item in the array is the function to call.
  */
 
@@ -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

src/ng/compile.js

@@ -531,7 +531,7 @@
  * $sce#getTrustedResourceUrl $sce.getTrustedResourceUrl}.
  *
  *
- * #### `replace` ([*DEPRECATED*!]
+ * #### `replace` (*DEPRECATED*)
  *
  * `replace` will be removed in next major release - i.e. v2.0).
  *

src/ng/q.js

@@ -15,7 +15,7 @@
  * $q can be used in two fashions --- one which is more similar to Kris Kowal's Q or jQuery's Deferred
  * implementations, and the other which resembles ES6 (ES2015) promises to some degree.
  *
- * # $q constructor
+ * ## $q constructor
  *
  * The streamlined ES6 style promise is essentially just using $q as a constructor which takes a `resolver`
  * function as the first argument. This is similar to the native Promise implementation from ES6,
@@ -103,7 +103,7 @@
  * For more on this please see the [Q documentation](https://github.com/kriskowal/q) especially the
  * section on serial or parallel joining of promises.
  *
- * # The Deferred API
+ * ## The Deferred API
  *
  * A new instance of deferred is constructed by calling `$q.defer()`.
  *
@@ -125,7 +125,7 @@
  * - promise – `{Promise}` – promise object associated with this deferred.
  *
  *
- * # The Promise API
+ * ## The Promise API
  *
  * A new promise instance is created when a deferred instance is created and can be retrieved by
  * calling `deferred.promise`.
@@ -157,7 +157,7 @@
  *   specification](https://github.com/kriskowal/q/wiki/API-Reference#promisefinallycallback) for
  *   more information.
  *
- * # Chaining promises
+ * ## Chaining promises
  *
  * Because calling the `then` method of a promise returns a new derived promise, it is easily
  * possible to create a chain of promises:
@@ -177,7 +177,7 @@
  * $http's response interceptors.
  *
  *
- * # Differences between Kris Kowal's Q and $q
+ * ## Differences between Kris Kowal's Q and $q
  *
  *  There are two main differences:
  *
@@ -187,7 +187,7 @@
  * - Q has many more features than $q, but that comes at a cost of bytes. $q is tiny, but contains
  *   all the important functionality needed for common async tasks.
  *
- * # Testing
+ * ## Testing
  *
  *  ```js
  *    it('should simulate promise', inject(function($q, $rootScope) {

src/ng/rootScope.js

@@ -143,7 +143,7 @@ function $RootScopeProvider() {
      * an in-depth introduction and usage examples.
      *
      *
-     * # Inheritance
+     * ## Inheritance
      * A scope can inherit from a parent scope, as in this example:
      * ```js
          var parent = $rootScope;
@@ -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;
@@ -1054,9 +1054,8 @@ function $RootScopeProvider() {
        * cycle of {@link ng.$exceptionHandler exception handling},
        * {@link ng.$rootScope.Scope#$digest executing watches}.
        *
-       * ## Life cycle
+       * **Life cycle: Pseudo-Code of `$apply()`**
        *
-       * # Pseudo-Code of `$apply()`
        * ```js
            function $apply(expr) {
              try {

src/ng/sce.js

@@ -463,13 +463,13 @@ function $SceDelegateProvider() {
  *
  * `$sce` is a service that provides Strict Contextual Escaping services to AngularJS.
  *
- * # Strict Contextual Escaping
+ * ## Strict Contextual Escaping
  *
  * Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only render
  * trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and
  * (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier.
  *
- * ## Overview
+ * ### Overview
  *
  * To systematically block XSS security bugs, AngularJS treats all values as untrusted by default in
  * HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically
@@ -485,7 +485,7 @@ function $SceDelegateProvider() {
  *
  * As of version 1.2, AngularJS ships with SCE enabled by default.
  *
- * ## In practice
+ * ### In practice
  *
  * Here's an example of a binding in a privileged context:
  *
@@ -522,7 +522,7 @@ function $SceDelegateProvider() {
  * (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to
  * build the trusted versions of your values.
  *
- * ## How does it work?
+ * ### How does it work?
  *
  * In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted
  * $sce.getTrusted(context, value)} rather than to the value directly.  Think of this function as
@@ -546,7 +546,7 @@ function $SceDelegateProvider() {
  * }];
  * ```
  *
- * ## Impact on loading templates
+ * ### Impact on loading templates
  *
  * This applies both to the {@link ng.directive:ngInclude `ng-include`} directive as well as
  * `templateUrl`'s specified by {@link guide/directive directives}.
@@ -566,7 +566,7 @@ function $SceDelegateProvider() {
  * won't work on all browsers.  Also, loading templates from `file://` URL does not work on some
  * browsers.
  *
- * ## This feels like too much overhead
+ * ### This feels like too much overhead
  *
  * It's important to remember that SCE only applies to interpolation expressions.
  *
@@ -590,7 +590,7 @@ function $SceDelegateProvider() {
  * security onto an application later.
  *
  * <a name="contexts"></a>
- * ## What trusted context types are supported?
+ * ### What trusted context types are supported?
  *
  * | Context             | Notes          |
  * |---------------------|----------------|
@@ -606,7 +606,7 @@ function $SceDelegateProvider() {
  * in AngularJS currently, so their corresponding `$sce.trustAs` functions aren't useful yet. This
  * might evolve.
  *
- * ## Format of items in {@link ng.$sceDelegateProvider#resourceUrlWhitelist resourceUrlWhitelist}/{@link ng.$sceDelegateProvider#resourceUrlBlacklist Blacklist} <a name="resourceUrlPatternItem"></a>
+ * ### Format of items in {@link ng.$sceDelegateProvider#resourceUrlWhitelist resourceUrlWhitelist}/{@link ng.$sceDelegateProvider#resourceUrlBlacklist Blacklist} <a name="resourceUrlPatternItem"></a>
  *
  *  Each element in these arrays must be one of the following:
  *
@@ -653,7 +653,7 @@ function $SceDelegateProvider() {
  *
  * Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} for an example.
  *
- * ## Show me an example using SCE.
+ * ### Show me an example using SCE.
  *
  * <example module="mySceApp" deps="angular-sanitize.js" name="sce-service">
  * <file name="index.html">

src/ngAnimate/module.js

@@ -8,9 +8,7 @@
  * The `ngAnimate` module provides support for CSS-based animations (keyframes and transitions) as well as JavaScript-based animations via
  * callback hooks. Animations are not enabled by default, however, by including `ngAnimate` the animation hooks are enabled for an AngularJS app.
  *
- * <div doc-module-components="ngAnimate"></div>
- *
- * # Usage
+ * ## Usage
  * Simply put, there are two ways to make use of animations when ngAnimate is used: by using **CSS** and **JavaScript**. The former works purely based
  * using CSS (by using matching CSS selectors/styles) and the latter triggers animations that are registered via `module.animation()`. For
  * both CSS and JS animations the sole requirement is to have a matching `CSS class` that exists both in the registered animation and within