another batch of doc fixes from ken

2 files changed, 36 insertions, 140 deletions

diff --git a/src/Angular.js b/src/Angular.js
index 4dbdc220..189d3f5f 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -871,145 +871,14 @@ function encodeUriQuery(val, pctEncodeSpaces) {
  * @TODO rename to ng:autobind to ng:autoboot
  *
  * @description
- * 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 adding a script tag in
- * your HTML file that contains `ng:autobind` attribute. This will:
+ * `ng:autobind` with no parameters tells angular to compile and manage the whole page.
  *
- * * 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;
-    &lt;html xmlns:ng="http://angularjs.org"&gt;
-     &lt;head&gt;
-      &lt;script type="text/javascript" src="http://code.angularjs.org/angular-0.9.3.min.js"
-              ng:autobind&gt;&lt;/script&gt;
-     &lt;/head&gt;
-     &lt;body&gt;
-       Hello {{'world'}}!
-     &lt;/body&gt;
-    &lt;/html&gt;
- * </pre>
- *
- * The reason why `ng:autobind` is needed at all is that angular does not want to be over-zealous
- * and assume the entire HTML document should be processed based solely on the fact you have
- * included the angular.js script.
- *
- * The `ng:autobind` attribute without any value tells angular to compile and manage the whole HTML
- * document. The compilation occurs as soon as the document is ready for DOM manipulation. Note that
- * 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 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 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;
-    &lt;html&gt;
-     &lt;head&gt;
-      &lt;script type="text/javascript"
-              src="http://code.angularjs.org/angular-0.9.3.min.js#autobind"&gt;&lt;/script&gt;
-     &lt;/head&gt;
-     &lt;body&gt;
-       &lt;div xmlns:ng="http://angularjs.org"&gt;
-         Hello {{'world'}}!
-       &lt;/div&gt;
-     &lt;/body&gt;
-    &lt;/html&gt;
- * </pre>
- *
- * 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 the angular script must match one of these naming
- * conventions:
- *
- * - `angular.js`
- * - `angular-min.js`
- * - `angular-x.x.x.js`
- * - `angular-x.x.x.min.js`
- * - `angular-x.x.x-xxxxxxxx.js` (dev snapshot)
- * - `angular-x.x.x-xxxxxxxx.min.js` (dev snapshot)
- * - `angular-bootstrap.js` (used for development of angular)
- *
- * 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 the manual bootstrap method instead.
- *
- * 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.
- *
- * <pre>
-    &lt;!doctype html&gt;
-    &lt;html xmlns:ng="http://angularjs.org"&gt;
-     &lt;head&gt;
-      &lt;script type="text/javascript" src="http://code.angularjs.org/angular-0.9.3.min.js"
-              ng:autobind&gt;&lt;/script&gt;
-      &lt;script type="text/javascript"&gt;
-       (angular.element(document).ready(function() {
-         angular.compile(document)();
-       })(document);
-      &lt;/script&gt;
-     &lt;/head&gt;
-     &lt;body&gt;
-       Hello {{'World'}}!
-     &lt;/body&gt;
-    &lt;/html&gt;
- * </pre>
- *
- * This is the sequence that your code should follow if you're bootstrapping angular on your own:
- *
- * 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 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
- * 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
- * to your page, create an alias, and set it to your unique domain:
- *
- * <pre>
- * &lt;html xmlns:ng="http://angularjs.org" xmlns:my="http://mydomain.com"&gt;
- * </pre>
- *
- *
- * ### 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.
+ * `ng:autobind="[root element ID]"` tells angular to compile and manage part of the docucment,
+ * starting at "root element ID".
  *
+ * For details on bootstrapping angular, see {@link guide/dev_guide.bootstrap Initializing Angular}
+ * in the Angular Developer Guide.
  */
 function angularInit(config, document){
   var autobind = config.autobind;
diff --git a/src/Compiler.js b/src/Compiler.js
index a03d24c4..d5eeae79 100644
--- a/src/Compiler.js
+++ b/src/Compiler.js
@@ -110,15 +110,15 @@ Template.prototype = {
  * @returns {function([scope][, cloneAttachFn])} a template function which is used to bind template
  * (a DOM element/tree) to a scope. Where:
  *
- *   * `scope` - A {@link angular.scope scope} to bind to. If none specified, then a new
+ *  * `scope` - A {@link angular.scope Scope} to bind to. If none specified, then a new
  *               root scope is created.
- *   * `cloneAttachFn` - If `cloneAttachFn` is provided, then the link function will clone the
+ *  * `cloneAttachFn` - If `cloneAttachFn` is provided, then the link function will clone the
  *               `template` and call the `cloneAttachFn` function allowing the caller to attach the
  *               cloned elements to the DOM document at the approriate place. The `cloneAttachFn` is
  *               called as: <br/> `cloneAttachFn(clonedElement, scope)` where:
  *
- *     * `clonedElement` - is a clone of the original `element` passed into the compiler.
- *     * `scope` - is the current scope with which the linking function is working with.
+ *      * `clonedElement` - is a clone of the original `element` passed into the compiler.
+ *      * `scope` - is the current scope with which the linking function is working with.
  *
  * Calling the template function returns the scope to which the element is bound to. It is either
  * the same scope as the one passed into the template function, or if none were provided it's the
@@ -148,6 +148,33 @@ Template.prototype = {
  *
  *     //now we have reference to the cloned DOM via `clone`
  *   </pre>
+ *
+ *
+ * Compiler Methods For Widgets and Directives:
+ *
+ * The following methods are available for use when you write your own widgets, directives,
+ * and markup.  (Recall that the compile function's this is a reference to the compiler.)
+ *
+ *  `compile(element)` - returns linker -
+ *  Invoke a new instance of the compiler to compile a DOM element and return a linker function.
+ *  You can apply the linker function to the original element or a clone of the original element.
+ *  The linker function returns a scope.
+ *
+ *  * `comment(commentText)` - returns element - Create a comment element.
+ *
+ *  * `element(elementName)` - returns element - Create an element by name.
+ *
+ *  * `text(text)` - returns element - Create a text element.
+ *
+ *  * `descend([set])` - returns descend state (true or false). Get or set the current descend
+ *  state. If true the compiler will descend to children elements.
+ *
+ *  * `directives([set])` - returns directive state (true or false). Get or set the current
+ *  directives processing state. The compiler will process directives only when directives set to
+ *  true.
+ *
+ * For information on how the compiler works, see the 
+ * {@link guide/dev_guide.compiler Angular HTML Compiler} section of the Developer Guide.
  */
 function Compiler(markup, attrMarkup, directives, widgets){
   this.markup = markup;