docs(forms): Update API docs for forms

- API forms (ng:model + controller, form + controller)
- fix some broken links
- ng:change, ng:model-instant

docs/content/api/angular.inputType.ngdoc

@@ -1,34 +0,0 @@
-@ngdoc overview
-@name angular.inputType
-@description
-
-Angular {@link guide/dev_guide.forms forms} allow you to build complex widgets. However for
-simple widget which are based on HTML input text element a simpler way of providing the validation
-and parsing is also provided. `angular.inputType` is a short hand for creating a widget which
-already has the DOM listeners and `$render` method supplied. The only thing which needs to
-be provided by the developer are the optional `$validate` listener and
-`$parseModel` or `$parseModel` methods.
-
-All `inputType` widgets support:
-
-  - CSS classes:
-    - **`ng-valid`**: when widget is valid.
-    - **`ng-invalid`**: when widget is invalid.
-    - **`ng-pristine`**: when widget has not been modified by user action.
-    - **`ng-dirty`**: when has been modified do to user action.
-
-  - Widget properties:
-    - **`$valid`**: When widget is valid.
-    - **`$invalid`**: When widget is invalid.
-    - **`$pristine`**: When widget has not been modified by user interaction.
-    - **`$dirty`**: When user has been modified by user interaction.
-    - **`$required`**: When the `<input>` element has `required` attribute. This means that the
-       widget will have `REQUIRED` validation error if empty.
-    - **`$disabled`**: When the `<input>` element has `disabled` attribute.
-    - **`$readonly`**: When the `<input>` element has `readonly` attribute.
-
-  - Widget Attribute Validators:
-    - **`required`**: Sets `REQUIRED` validation error key if the input is empty
-    - **`ng:pattern`** Sets `PATTERN` validation error key if the value does not match the
-      RegExp pattern expression. Expected value is `/regexp/` for inline patterns or `regexp` for
-      patterns defined as scope expressions.

docs/content/api/angular.module.ng.$compileProvider.directive.ngdoc

@@ -58,8 +58,8 @@ the following example.
 During the compilation process the {@link angular.module.ng.$compile compiler} matches text and
 attributes using the {@link angular.module.ng.$interpolate $interpolate} service to see if they
 contain embedded expressions. These expressions are registered as {@link
-angular.module.ng.$rootScope.Scope#.watch watches} and will update as part of normal {@link
-angular.module.ng.$rootScope.Scope#.digest digest} cycle. An example of interpolation is shown
+angular.module.ng.$rootScope.Scope#$watch watches} and will update as part of normal {@link
+angular.module.ng.$rootScope.Scope#$digest digest} cycle. An example of interpolation is shown
 here:
 
 <pre>
@@ -87,7 +87,7 @@ Compilation of HTML happens in three phases:
   3. Link the template with scope by calling the liking function returned from the previous step.
   This in turn will call the linking function of the individual directives allowing them to
   register any listeners on the elements and set up any {@link
-  angular.module.ng.$rootScope.Scope#.watch watches} with the {@link
+  angular.module.ng.$rootScope.Scope#$watch watches} with the {@link
   angular.module.ng.$rootScope.Scope scope}. The result of this is a live binding between the
   scope and the DOM. A change in the scope is reflected in the DOM.
 
@@ -417,8 +417,8 @@ compiler}. The attributes are:
     append the template to the element.
 
   * `transclude` - compile the content of the element and make it available to the directive.
-    Typically used with {@link api/angular.module.ng.$compileProvider.directive.ng-transclude
-    ng-transclude}. The advantage of transclusion is that the linking function receives a
+    Typically used with {@link api/angular.module.ng.$compileProvider.directive.ng:transclude
+    ng:transclude}. The advantage of transclusion is that the linking function receives a
     transclusion function which is pre-bound to the correct scope. In a typical setup the widget
     creates an `isolate` scope, but the transclusion is not a child, but a sibling of the `isolate`
     scope. This makes it possible for the widget to have private state, and the transclusion to
@@ -451,7 +451,7 @@ compile functions takes the following arguments.
 
   * `tAttrs` - template attributes - Normalized list of attributes declared on this element shared
     between all directive compile functions. See {@link
-    angular.module.ng.$compileProvider.directive.Attributes Attributes}
+    #Attributes Attributes}
 
   * `transclude` - A transclude linking function: `function(scope, cloneLinkingFn)`.
 
@@ -470,15 +470,14 @@ executed after the template has been cloned. This is where most of the directive
 put.
 
   * `scope` - {@link angular.module.ng.$rootScope.Scope Scope} - The scope to be used by the
-    directive for registering {@link angular.module.ng.$rootScope.Scope#.watch watches}.
+    directive for registering {@link angular.module.ng.$rootScope.Scope#$watch watches}.
 
   * `iElement` - instance element - The element where the directive is to be used. It is safe to
     manipulate the children of the element only in `postLink` function since the children have
     already been linked.
 
   * `iAttrs` - instance attributes - Normalized list of attributes declared on this element shared
-    between all directive linking functions. See {@link
-    angular.module.ng.$compileProvider.directive.Attributes Attributes}
+    between all directive linking functions. See {@link #Attributes Attributes}
 
   * `controller` - a controller instance - A controller instance if at least one directive on the
     element defines a controller. The controller is shared among all the directives, which allows
@@ -495,6 +494,7 @@ compiler linking function will fail to locate the correct elements for linking.
 
 Executed after the child elements are linked. Safe to do DOM transformation in here.
 
+<a name="Attributes"></a>
 ## Attributes
 
 The attributes object - passed as a parameter in the link() or compile() functions - is a way of

docs/content/guide/dev_guide.bootstrap.manual_bootstrap.ngdoc

@@ -7,7 +7,7 @@ angular, but advanced users who want more control over the initialization proces
 the manual bootstrapping method instead.
 
 The best way to get started with manual bootstrapping is to look at the what happens when you use
-{@link api/angular.directive.ng:app ng:app}, by showing each step of the process
+{@link api/angular.module.ng.$compileProvider.directive.ng:app ng:app}, by showing each step of the process
 explicitly.
 
 <pre>

docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc

@@ -2,8 +2,8 @@
 @name Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works
 @description
 
-The {@link angular.module.ng.$compile compiler} is responsible for applying
-{@link angular.module.ng.$compileProvider.directive directives} to the HTML. The directives
+The {@link api/angular.module.ng.$compile compiler} is responsible for applying
+{@link api/angular.module.ng.$compileProvider.directive directives} to the HTML. The directives
 extend the behavior of HTML elements and can effect the DOM structure, presentation, and behavior.
 This allows Angular to teach the browser new tricks.
 
@@ -13,7 +13,7 @@ function. The result of the compilation process is a linking function. The linki
 can be used on the template clones to quickly bind the directives with the scope.
 
 The result of the compilation process is a live view. We say 'live' since any changes to the
-model attached to the {@link angular.module.ng.$rootScope.Scope scope} are reflected in the view,
+model attached to the {@link api/angular.module.ng.$rootScope.Scope scope} are reflected in the view,
 and any changes in the view are reflected in the scope. This makes the scope the 'single source of
 truth'.
 
@@ -21,7 +21,7 @@ Since directives allow attachment of behavior to the HTML, the angular philosoph
 HTML as Domain Specific Language (DSL) when building an application. For example it may be useful
 to declare `TabPanel` directive, or `KeyboardShortcut` directive when for an application.
 
-For details on how directives are created see {@link angular.module.ng.$compileProvider.directive
+For details on how directives are created see {@link api/angular.module.ng.$compileProvider.directive
 directives}
 
 ## Related Topics

docs/content/guide/dev_guide.scopes.internals.ngdoc

@@ -46,7 +46,7 @@ reside on a child scope, if a property read does not find the property on a scop
 recursively check the parent scope, grandparent scope, etc. all the way to the root scope before
 defaulting to undefined.
 
-{@link angular.module.ng.$compileProvider.directive directives} associated with elements
+{@link api/angular.module.ng.$compileProvider.directive directives} associated with elements
 (ng:controller, ng:repeat, ng:include, etc.) create new child scopes that inherit properties from
 the current parent scope. Any code in Angular is free to create a new scope. Whether or not your
 code does so is an implementation detail of the directive, that is, you can decide when or if this
@@ -117,9 +117,9 @@ scopes come into play throughout and get a sense of their interactions.
 1. At application compile time, a root scope is created and is attached to the root `<HTML>` DOM
 element.
 2. During the compilation phase, the {@link dev_guide.compiler compiler} matches {@link
-angular.module.ng.$compileProvider.directive directives} against the DOM template. The directives
+api/angular.module.ng.$compileProvider.directive directives} against the DOM template. The directives
 usually fall into one of two categories:
-   - Observing {@link angular.module.ng.$compileProvider.directive directives}, such as double-curly
+   - Observing {@link api/angular.module.ng.$compileProvider.directive directives}, such as double-curly
     expressions `{{expression}}`, register listeners using the {@link
     api/angular.module.ng.$rootScope.Scope#$watch $watch()} method. This type of directive needs to
     be notified whenever the expression changes so that it can update the view.
@@ -133,7 +133,7 @@ api/angular.module.ng.$rootScope.Scope#$apply $apply()} method so that all liste
 
 
 ### Directives that create scopes
-In most cases, {@link angular.module.ng.$compileProvider.directive directives} and scopes interact but do not create new
+In most cases, {@link api/angular.module.ng.$compileProvider.directive directives} and scopes interact but do not create new
 instances of scope. However, some directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng:controller
 ng:controller} and {@link api/angular.module.ng.$compileProvider.directive.@ng:repeat ng:repeat}, create new child scopes using
 the {@link api/angular.module.ng.$rootScope.Scope#$new $new()} method and then attach the child scope to the

docs/src/templates/docs.css

@@ -295,6 +295,9 @@ li {
   margin-left: 4em;
 }
 
+#content-list .level-6 {
+  margin-left: 5em;
+}
 
 #content-list a.current {
   font-weight: bold;
@@ -509,7 +512,7 @@ td.empty-corner-lt {
   width: 360px;
 }
 
-.error {
+.doc-example-live .error {
    color: red;
 }
 

src/loader.js

@@ -171,7 +171,7 @@ function setupModuleLoader(window) {
            * @param {Function} directiveFactory Factory function for creating new instance of
            * directives.
            * @description
-           * See {@link angular.module.ng.$compileProvider#directive $compileProvider.directive()}.
+           * See {@link angular.module.ng.$compileProvider.directive $compileProvider.directive()}.
            */
           directive: invokeLater('$compileProvider', 'directive'),
 

src/scenario/dsl.js

@@ -199,11 +199,11 @@ angular.scenario.dsl('binding', function() {
 angular.scenario.dsl('input', function() {
   var chain = {};
 
-  chain.enter = function(value) {
+  chain.enter = function(value, event) {
     return this.addFutureAction("input '" + this.name + "' enter '" + value + "'", function($window, $document, done) {
       var input = $document.elements('[ng\\:model="$1"]', this.name).filter(':input');
       input.val(value);
-      input.trigger('blur');
+      input.trigger(event || 'blur');
       done();
     });
   };

src/widget/form.js

@@ -1,5 +1,27 @@
 'use strict';
 
+
+/**
+ * @ngdoc object
+ * @name angular.module.ng.$compileProvider.directive.form.FormController
+ *
+ * @property {boolean} pristine True if user has not interacted with the form yet.
+ * @property {boolean} dirty True if user has already interacted with the form.
+ * @property {boolean} valid True if all of the containg widgets are valid.
+ * @property {boolean} invalid True if at least one containing widget is invalid.
+ *
+ * @property {Object} error Is an object hash, containing references to all invalid widgets, where
+ *
+ *  - keys are error ids (such as `REQUIRED`, `URL` or `EMAIL`),
+ *  - values are arrays of widgets that are invalid with given error.
+ *
+ * @description
+ * Form is a controller that keeps track of all registered widgets.
+ *
+ * Each {@link angular.module.ng.$compileProvider.directive.form form} directive creates an instance
+ * of `FormController`.
+ *
+ */
 FormController.$inject = ['$scope', 'name'];
 function FormController($scope, name) {
   var form = this,
@@ -73,6 +95,19 @@ function FormController($scope, name) {
   }
 }
 
+/**
+ * @ngdoc function
+ * @name angular.module.ng.$compileProvider.directive.form.FormController#registerWidget
+ * @methodOf angular.module.ng.$compileProvider.directive.form.FormController
+ * @function
+ *
+ * @param {Object} widget Widget to register (controller of a widget)
+ * @param {string=} alias Name alias of the widget.
+ *                        (If specified, widget will be accesible as a form property)
+ *
+ * @description
+ *
+ */
 FormController.prototype.registerWidget = function(widget, alias) {
   if (alias && !this.hasOwnProperty(alias)) {
     widget.widgetId = alias;
@@ -82,16 +117,15 @@ FormController.prototype.registerWidget = function(widget, alias) {
 
 
 /**
- * @ngdoc directive
+ * @ngdoc widget
  * @name angular.module.ng.$compileProvider.directive.form
  *
  * @scope
  * @description
- * Angular widget that creates a form scope using the
- * {@link angular.module.ng.$formFactory $formFactory} API. The resulting form scope instance is
- * attached to the DOM element using the jQuery `.data()` method under the `$form` key.
- * See {@link guide/dev_guide.forms forms} on detailed discussion of forms and widgets.
+ * Directive that instantiates
+ * {@link angular.module.ng.$compileProvider.directive.form.FormController Form} controller.
  *
+ * If `name` attribute is specified, the controller is published to the scope as well.
  *
  * # Alias: `ng:form`
  *
@@ -101,9 +135,16 @@ FormController.prototype.registerWidget = function(widget, alias) {
  * element nesting.
  *
  *
+ * # CSS classes
+ *  - `ng-valid` Is set if the form is valid.
+ *  - `ng-invalid` Is set if the form is invalid.
+ *  - `ng-pristine` Is set if the form is pristine.
+ *  - `ng-dirty` Is set if the form is dirty.
+ *
+ *
  * # Submitting a form and preventing default action
  *
- * Since the role of forms in client-side Angular applications is different than in old-school
+ * Since the role of forms in client-side Angular applications is different than in classical
  * roundtrip apps, it is desirable for the browser not to translate the form submission into a full
  * page reload that sends the data to the server. Instead some javascript logic should be triggered
  * to handle the form submission in application specific way.
@@ -128,7 +169,8 @@ FormController.prototype.registerWidget = function(widget, alias) {
  * hitting enter in any of the input fields will trigger the click handler on the *first* button or
  * input[type=submit] (`ng:click`) *and* a submit handler on the enclosing form (`ng:submit`)
  *
- * @param {string=} name Name of the form.
+ * @param {string=} name Name of the form. If specified, the form controller will be published into
+ *                       related scope, under this name.
  *
  * @example
     <doc:example>