doc fix - ng:autobind, ng:controller and more

1 files changed, 33 insertions, 28 deletions

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 <angular/> 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:
  *
  * <pre>
     &lt;!doctype html&gt;
@@ -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:
  *
  * <pre>
     &lt;!doctype html&gt;
@@ -920,14 +924,14 @@ function encodeUriQuery(val, pctEncodeSpaces) {
     &lt;/html&gt;
  * </pre>
  *
- * 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 <angular/>, 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 <angular/> 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.
  *
  * <pre>
  * &lt;html xmlns:ng="http://angularjs.org"&gt;
  * </pre>
  *
  *
- * ## 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) {
  * </pre>
  *
  *
- * ## Global Object
- * The <angular/> 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.
  *
  */