From 3d787ab6f4fecf9168159e460fcd148120aa4c43 Mon Sep 17 00:00:00 2001
From: Kenneth R. Culp
Date: Fri, 8 Apr 2011 16:03:39 -0700
Subject: doc fix - ng:autobind, ng:controller and more
---
src/Angular.js | 61 ++++++++++++++++++++++++++++-------------------------
src/directives.js | 63 ++++++++++++++++++++++++++++++++-----------------------
src/filters.js | 6 +++---
src/widgets.js | 25 ++++++++++++----------
4 files changed, 87 insertions(+), 68 deletions(-)
(limited to 'src')
diff --git a/src/Angular.js b/src/Angular.js
index 512ee829..1762c11d 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -870,13 +870,17 @@ function encodeUriQuery(val, pctEncodeSpaces) {
* @TODO rename to ng:autobind to ng:autoboot
*
* @description
- * This section explains how to bootstrap your application with angular, using either the angular
- * javascript file, or manually.
+ * This doc explains how to bootstrap your application with angular. You can either use
+ * `ng:autobind` script tag attribute or perform a manual bootstrap.
*
* # Auto-bootstrap with `ng:autobind`
- * The simplest way to get an application up and running is by inserting a script tag in
- * your HTML file that bootstraps the `http://code.angularjs.org/angular-x.x.x.min.js` code and uses
- * the special `ng:autobind` attribute, like in this snippet of HTML:
+ * The simplest way to get an angular application up and running is by adding a script tag in
+ * your HTML file that contains `ng:autobind` attribute. This will:
+ *
+ * * Load the angular script
+ * * Tell angular to compile the entire document (or just its portion if the attribute has a value)
+ *
+ * For example:
*
*
<!doctype html>
@@ -896,14 +900,14 @@ function encodeUriQuery(val, pctEncodeSpaces) {
* you don't need to explicitly add an `onLoad` event handler; auto bind mode takes care of all the
* work for you.
*
- * In order to compile only a part of the document, specify the id of the element that should be
- * compiled as the value of the `ng:autobind` attribute, e.g. `ng:autobind="angularContent"`.
+ * In order to compile only a part of the document with a root element, specify the id of the root
+ * element as the value of the `ng:autobind` attribute, e.g. `ng:autobind="angularContent"`.
*
*
* ## Auto-bootstrap with `#autobind`
- * In rare cases when you can't define the `ng` namespace before the script tag (e.g. in some CMS
- * systems, etc), it is possible to auto-bootstrap angular by appending `#autobind` to the script
- * src URL, like in this snippet:
+ * In some rare cases you can't define the `ng:` prefix before the script tag's attribute (e.g. in
+ * some CMS systems). In these situations it is possible to auto-bootstrap angular by appending
+ * `#autobind` to the script `src` URL, like in this snippet:
*
*
<!doctype html>
@@ -920,14 +924,14 @@ function encodeUriQuery(val, pctEncodeSpaces) {
</html>
*
*
- * In this case it's the `#autobind` URL fragment that tells angular to auto-bootstrap.
+ * In this snippet it is the `#autobind` URL fragment that tells angular to auto-bootstrap.
*
* Similarly to `ng:autobind`, you can specify an element id that should be exclusively targeted for
* compilation as the value of the `#autobind`, e.g. `#autobind=angularContent`.
*
* ## Filename Restrictions for Auto-bootstrap
* In order for us to find the auto-bootstrap script attribute or URL fragment, the value of the
- * `script` `src` attribute that loads angular script must match one of these naming
+ * `script` `src` attribute that loads the angular script must match one of these naming
* conventions:
*
* - `angular.js`
@@ -938,15 +942,15 @@ function encodeUriQuery(val, pctEncodeSpaces) {
* - `angular-x.x.x-xxxxxxxx.min.js` (dev snapshot)
* - `angular-bootstrap.js` (used for development of angular)
*
- * Optionally, any of the filename format above can be prepended with relative or absolute URL that
- * ends with `/`.
+ * Optionally, any of the filename formats above can be prepended with a relative or absolute URL
+ * that ends with `/`.
*
*
- * ## Manual Bootstrap
- * Using auto-bootstrap is a handy way to start using , but advanced users who want more
- * control over the initialization process might prefer to use manual bootstrap instead.
+ * # Manual Bootstrap
+ * Using auto-bootstrap is a handy way to start using angular, but advanced users who want more
+ * control over the initialization process might prefer to use the manual bootstrap method instead.
*
- * The best way to get started with manual bootstraping is to look at the magic behind `ng:autobind`
+ * The best way to get started with manual bootstraping is to look at the magic behind `ng:autobind`,
* by writing out each step of the autobind process explicitly. Note that the following code is
* equivalent to the code in the previous section.
*
@@ -970,22 +974,23 @@ function encodeUriQuery(val, pctEncodeSpaces) {
*
* This is the sequence that your code should follow if you're bootstrapping angular on your own:
*
- * * After the page is loaded, find the root of the HTML template, which is typically the root of
- * the document.
- * * Run the HTML compiler, which converts the templates into an executable, bi-directionally bound
- * application.
+ * 1. After the page is loaded, find the root of the HTML template, which is typically the root of
+ * the document.
+ * 2. Run the HTML compiler, which converts the templates into an executable, bi-directionally bound
+ * application.
*
*
- * ##XML Namespace
- * *IMPORTANT:* When using you must declare the ng namespace using the xmlns tag. If you
- * don't declare the namespace, Internet Explorer does not render widgets properly.
+ * ## XML Namespace
+ * *IMPORTANT:* When using angular, you must declare the ng namespace using the xmlns tag. If you
+ * don't declare the namespace, Internet Explorer older than 9 does not render widgets properly. The
+ * namespace must be declared even if you use HTML instead of XHTML.
*
*
* <html xmlns:ng="http://angularjs.org">
*
*
*
- * ## Create your own namespace
+ * ### Create your own namespace
* If you want to define your own widgets, you must create your own namespace and use that namespace
* to form the fully qualified widget name. For example, you could map the alias `my` to your domain
* and create a widget called my:widget. To create your own namespace, simply add another xmlsn tag
@@ -996,8 +1001,8 @@ function encodeUriQuery(val, pctEncodeSpaces) {
*
*
*
- * ## Global Object
- * The script creates a single global variable `angular` in the global namespace. All
+ * ### Global Object
+ * The angular script creates a single global variable `angular` in the global namespace. All
* APIs are bound to fields of this global object.
*
*/
diff --git a/src/directives.js b/src/directives.js
index 32860a1e..bd02dd17 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -4,7 +4,7 @@
* @name angular.directive.ng:init
*
* @description
- * `ng:init` attribute allows the for initialization tasks to be executed
+ * The `ng:init` attribute specifies initialization tasks to be executed
* before the template enters execution mode during bootstrap.
*
* @element ANY
@@ -37,21 +37,31 @@ angularDirective("ng:init", function(expression){
* @name angular.directive.ng:controller
*
* @description
- * To support the Model-View-Controller design pattern, it is possible
- * to assign behavior to a scope through `ng:controller`. The scope is
- * the MVC model. The HTML (with data bindings) is the MVC view.
- * The `ng:controller` directive specifies the MVC controller class
+ * The `ng:controller` directive assigns behavior to a scope. This is a key aspect of how angular
+ * supports the principles behind the Model-View-Controller design pattern.
+ *
+ * MVC components in angular:
+ *
+ * * Model — The Model is data in scope properties; scopes are attached to the DOM.
+ * * View — The template (HTML with data bindings) is rendered into the View.
+ * * Controller — The `ng:controller` directive specifies a Controller class; the class has
+ * methods that typically express the business logic behind the application.
+ *
+ * Note that an alternative way to define controllers is via the `{@link angular.service.$route}`
+ * service.
*
* @element ANY
- * @param {expression} expression {@link guide.expression Expression} to eval.
+ * @param {expression} expression Name of a globally accessible constructor function or an
+ * {@link guide.expression expression} that on the current scope evaluates to a constructor
+ * function.
*
* @example
- * Here is a simple form for editing the user contact information. Adding, removing clearing and
- * greeting are methods which are declared on the controller (see source tab). These methods can
- * easily be called from the angular markup. Notice that the scope becomes the controller's class
- * this. This allows for easy access to the view data from the controller. Also notice that any
- * changes to the data are automatically reflected in the view without the need to update it
- * manually.
+ * Here is a simple form for editing user contact information. Adding, removing, clearing, and
+ * greeting are methods declared on the controller (see source tab). These methods can
+ * easily be called from the angular markup. Notice that the scope becomes the `this` for the
+ * controller's instance. This allows for easy access to the view data from the controller. Also
+ * notice that any changes to the data are automatically reflected in the View without the need
+ * for a manual update.