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
2017-09-27 20:37:35 +02:00
parent ddd78bd3e4
commit 87273022f2
22 changed files with 41 additions and 107 deletions
@@ -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 $}
@@ -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.
@@ -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
@@ -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
@@ -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.
@@ -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]*)$/;
@@ -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,7 +165,7 @@ 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
@@ -173,10 +173,10 @@ function annotate(fn, strictDi, name) {
 * *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
@@ -531,7 +531,7 @@
 * $sce#getTrustedResourceUrl $sce.getTrustedResourceUrl}.
 *
 *
- * #### `replace` ([*DEPRECATED*!]
+ * #### `replace` (*DEPRECATED*)
 *
 * `replace` will be removed in next major release - i.e. v2.0).
 *
@@ -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) {
@@ -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 {
@@ -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">
@@ -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
@@ -10,8 +10,6 @@
 * attributes that convey state or semantic information about the application for users
 * of assistive technologies, such as screen readers.
 *
- * <div doc-module-components="ngAria"></div>
- *
 * ## Usage
 *
 * For ngAria to do its magic, simply include the module `ngAria` as a dependency. The following
@@ -5,13 +5,8 @@
 * @name ngCookies
 * @description
 *
- * # ngCookies
- *
 * The `ngCookies` module provides a convenient wrapper for reading and writing browser cookies.
 *
- *
- * <div doc-module-components="ngCookies"></div>
- *
 * See {@link ngCookies.$cookies `$cookies`} for usage.
 */

@@ -20,7 +20,7 @@ var jqLite;
 * Currently, the ngMessages module only contains the code for the `ngMessages`, `ngMessagesInclude`
 * `ngMessage` and `ngMessageExp` directives.
 *
- * # Usage
+ * ## Usage
 * The `ngMessages` directive allows keys in a key/value collection to be associated with a child element
 * (or 'message') that will show or hide based on the truthiness of that key's value in the collection. A common use
 * case for `ngMessages` is to display error messages for inputs using the `$error` object exposed by the
@@ -2356,15 +2356,10 @@ angular.mock.$ComponentControllerProvider = ['$compileProvider',
 * @packageName angular-mocks
 * @description
 *
- * # ngMock
- *
 * The `ngMock` module provides support to inject and mock AngularJS services into unit tests.
 * In addition, ngMock also extends various core AngularJS services such that they can be
 * inspected and controlled in a synchronous manner within test code.
 *
- *
- * <div doc-module-components="ngMock"></div>
- *
 * @installation
 *
 *  First, download the file:
@@ -8,14 +8,9 @@
 * @packageName angular-parse-ext
 * @description
 *
- * # ngParseExt
- *
 * The `ngParseExt` module provides functionality to allow Unicode characters in
 * identifiers inside AngularJS expressions.
 *
- *
- * <div doc-module-components="ngParseExt"></div>
- *
 * This module allows the usage of any identifier that follows ES6 identifier naming convention
 * to be used as an identifier in an AngularJS expression. ES6 delegates some of the identifier
 * rules definition to Unicode, this module uses ES6 and Unicode 8.0 identifiers convention.
@@ -48,14 +48,9 @@ function shallowClearAndCopy(src, dst) {
 * @name ngResource
 * @description
 *
- * # ngResource
- *
 * The `ngResource` module provides interaction support with RESTful services
 * via the $resource service.
 *
- *
- * <div doc-module-components="ngResource"></div>
- *
 * See {@link ngResource.$resourceProvider} and {@link ngResource.$resource} for usage.
 */

@@ -10,7 +10,6 @@ ngRouteModule.directive('ngView', ngViewFillContentFactory);
 * @restrict ECA
 *
 * @description
- * # Overview
 * `ngView` is a directive that complements the {@link ngRoute.$route $route} service by
 * including the rendered template of the current route into the main layout (`index.html`) file.
 * Every time the current route changes, the included view changes with it according to the
@@ -14,15 +14,11 @@ var noop;
 * @name ngRoute
 * @description
 *
- * # ngRoute
- *
 * 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`.
 *
- *
- * <div doc-module-components="ngRoute"></div>
 */
 /* global -ngRouteModule */
 var ngRouteModule = angular.
@@ -27,13 +27,8 @@ var htmlSanitizeWriter;
 * @name ngSanitize
 * @description
 *
- * # ngSanitize
- *
 * The `ngSanitize` module provides functionality to sanitize HTML.
 *
- *
- * <div doc-module-components="ngSanitize"></div>
- *
 * See {@link ngSanitize.$sanitize `$sanitize`} for usage.
 */

@@ -5,17 +5,12 @@
 * @name ngTouch
 * @description
 *
- * # ngTouch
- *
 * The `ngTouch` module provides helpers for touch-enabled devices.
 * The implementation is based on jQuery Mobile touch event handling
- * ([jquerymobile.com](http://jquerymobile.com/)).
- *
+ * ([jquerymobile.com](http://jquerymobile.com/)). *
 *
 * See {@link ngTouch.$swipe `$swipe`} for usage.
 *
- * <div doc-module-components="ngTouch"></div>
- *
 */

 // define ngTouch module