Peach

docs/angular.directive.ngdoc

@@ -4,50 +4,57 @@
 @namespace Namespace for all directives.
 
 @description
-A directive is an HTML attribute that you can use in an existing HTML element type or in a
-DOM element type that you create as {@link angular.widget}, to modify that element's
-properties. You can use any number of directives per element.
+An angular directive is an HTML attribute.  You can use directives to modify a DOM element's
+properties.  The element you modify can be an existing HTML element type, or a DOM element type
+that you create as an {@link angular.widget}. You can use any number of directives per element.
 
-For example, you can add the ng:bind directive as an attribute of an HTML span element, as in
-`<span ng:bind="1+2"></span>`. How does this work? The compiler passes the attribute value
-`1+2` to the ng:bind extension, which in turn tells the {@link angular.scope} to watch that
-expression and report changes. On any change it sets the span text to the expression value.
+For example, you could add the {@link angular.directive.ng:bind ng:bind} directive as an attribute
+of an HTML span element, as in:
+
+         <span ng:bind="1+2"></span>  
+
+How does this work? The angular {@link guide.compiler compiler} passes the attribute value `1+2`
+to the `ng:bind` extension, which in turn tells the {@link angular.scope} to watch that expression
+in the data model and report changes. On any change to the expression in the model, the scope sets
+the span text to the expression value. 
 
 Here's how to define {@link angular.directive.ng:bind ng:bind}:
 <pre>
-  angular.directive('ng:bind', function(expression, compiledElement) {
-    var compiler = this;
-    return function(linkElement) {
-      var currentScope = this;
-      currentScope.$watch(expression, function(value) {
-        linkElement.text(value);
-      });
-    };
-  });
+angular.directive('ng:bind', function(expression, compiledElement) {
+  var compiler = this;
+  return function(linkElement) {
+    var currentScope = this;
+    currentScope.$watch(expression, function(value) {
+      linkElement.text(value);
+    });
+  };
+});
 </pre>
 
-# Directive vs. Attribute Widget
-Both [attribute widgets](#!angular.widget) and directives can compile a DOM element
-attribute. So why have two different ways to do the same thing? The answer is that order
-matters, but we have no control over the order in which attributes are read. To solve this
-we apply attribute widget before the directive.
+# Directives vs. Attribute Widgets
+Directives and attribute widgets look the same in a template (`ng:init` is a directive,
+`ng:repeat` is an attribute widget), but they behave slightly differently.
+
+[Attribute widgets](#!angular.widget) and directives can both compile a DOM element
+attribute, so why have two different ways to do the same thing? The answer is that the order in
+which attribute directives get processed matters, but we have no control over the order in which
+attributes are read. To solve this, we use an attribute widget.  Widgets always run before
+directives in a particular element. So we apply an attribute widget before any directives when we
+need to control the order in which attributes are processed.  Widgets may manipulate the DOM,
+whereas directives are not expected to do so, and so directives run after widgets.
 
-For example, consider this piece of HTML, which uses the directives `ng:repeat`, `ng:init`,
-and `ng:bind`:
+For example, consider this piece of HTML, which uses `ng:repeat`, `ng:init`, and `ng:bind`:
 <pre>
-  <ul ng:init="people=['mike', 'mary']">
-    <li ng:repeat="person in people" ng:init="a=a+1" ng:bind="person"></li>
-  </ul>
+<ul ng:init="people=['mike', 'mary']">
+  <li ng:repeat="person in people" ng:init="a=a+1" ng:bind="person"></li>
+</ul>
 </pre>
 
 Notice that the order of execution matters here. We need to execute
 {@link angular.directive.ng:repeat ng:repeat} before we run the
-{@link angular.directive.ng:init ng:init} and `ng:bind` on the `<li/>;`. This is because we
-want to run the `ng:init="a=a+1` and `ng:bind="person"` once for each person in people. We
-could not have used directive to create this template because attributes are read in an
-unspecified order and there is no way of guaranteeing that the repeater attribute would
-execute first. Using the `ng:repeat` attribute directive ensures that we can transform the
-DOM element into a template.
-
-Widgets run before directives. Widgets may manipulate the DOM whereas directives are not
-expected to do so, and so they run last.
+{@link angular.directive.ng:init ng:init} and {@link angular.directive.ng:bind ng:bind} on the
+`<li/>;`. This is because we want to run the `ng:init="a=a+1` and `ng:bind="person"` once for each
+`person in people`. We could not have used a directive to implement the repeater in this template,
+because attributes are read in an unspecified order and there is no way of guaranteeing that the
+repeater attribute would execute first. Using the `ng:repeat` attribute widget ensures that we can
+transform the DOM element into the template we intended.

docs/angular.element.ngdoc

@@ -4,7 +4,7 @@
 @function
 
 @description
-Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element.
+Wraps a raw DOM element or HTML string as a [jQuery](http://jquery.com) element.
 `angular.element` is either an alias for [jQuery](http://api.jquery.com/jQuery/) function if
 jQuery is loaded or a function that wraps the element or string in angular's jQuery lite
 implementation.
@@ -40,8 +40,7 @@ raw DOM references.
 - [text()](http://api.jquery.com/text/)
 - [trigger()](http://api.jquery.com/trigger/)
 
-## Additionally these methods extend the jQuery and  are available in both jQuery and jQuery lite
-version:
+## These methods extend jQuery and are available in both jQuery and jQuery lite versions:
 
 - `scope()` - retrieves the current angular scope of the element.
 

docs/angular.markup.ngdoc

@@ -4,39 +4,41 @@
 
 @description
 #Overview
-Markups allow the angular compiler to transform content of DOM elements or portions of this content
-into other text or DOM elements for further compilation. Markup extensions do not themselves produce
-linking functions. Think of markup as a way to produce shorthand for a {@link angular.widget widget}
- or a {@link angular.directive directive}.
+Markups allow the angular compiler to transform the content of DOM elements (or portions of the 
+content) into other text or DOM elements for further compilation. Markup extensions do not 
+themselves produce linking functions. Think of markup as a way to produce shorthand for a {@link 
+angular.widget widget} or a {@link angular.directive directive}.
 
-#`{{}}` (double curly) built-in markup
-`{{}}` markup is a built-in markup, which translates the enclosed expression into an
-{@link angular.directive.ng:bind ng:bind} directive. It simply transforms
+# The Double Curly Braces Markup
+The `{{ }}` markup is built-in to angular. It translates an enclosed expression into an
+{@link angular.directive.ng:bind ng:bind} directive:
 
 <pre>
 {{expression}}
 </pre>
 
-to:
+is translated to:
 
 <pre>
 <span ng:bind="expression"></span>
 </pre>
 
-For example `{{1+2}}` is easier to write and understand than `<span ng:bind="1+2"></span>`. The
+For example, `{{1+2}}` is easier to write and understand than `<span ng:bind="1+2"></span>`. The
 expanded elements are then {@link guide.compiler compiled} normally.
 
-# Custom markup
+# Custom Markup
 Let's say you want to define this shorthand for a horizontal rule: `---` for `<hr/>`.
 
-In other words, this HTML:
+In other words, you want this HTML:
+
 <pre>
 header
 ---
 footer
 </pre>
 
-should translate to:
+to translate to:
+
 <pre>
 header
 <hr/>
@@ -60,7 +62,7 @@ angular.markup('---', function(text, textNode, parentElement) {
 });
 </pre>
 
-Unlike {@link angular.widget widgets} and {@link angular.directive directives}, in which the
-compiler matches the name of handler function to a DOM element or attribute name, for markup the
-compiler calls every markup handler for every text node, giving the handler a chance to transform
-the text. The markup handler needs to find all the matches in the text.
+For {@link angular.widget widgets} and {@link angular.directive directives}, the compiler matches 
+the name of the handler function to a DOM element or attribute name.  But for markup, the compiler 
+calls every markup handler for every text node, giving the handler a chance to transform the text. 
+The markup handler needs to find all the matches in the text.

docs/guide.bootstrap.ngdoc

@@ -62,36 +62,37 @@ equivalent to the code in the previous section.
 
 This is the sequence that your code should follow if you're writing your own manual binding code:
 
- * After the page is loaded, find the root of the HTML template, which is typically the root of
+1. 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
+1. 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.
+**IMPORTANT:** When using angular, you must declare the `ng` namespace using the `xmlns` tag in
+the following scenarios:
 
-<pre>
-<html  xmlns:ng="http://angularjs.org">
-</pre>
+* If you are using XHTML
+* If you are targeting IE older than 9 (regardless of whether you are using XHTML or HTML).  
+
+If you don't declare the `ng` namespace in either of these scenarios, your browser will not render
+widgets properly.  To declare the `ng` namespace:
+
+        <html xmlns:ng="http://angularjs.org">
 
 
 # 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 xmlns tag
-to your page, create an alias, and set it to your unique domain:
+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 `xmlns`
+tag to your page, create an alias, and set it to your unique domain:
 
-<pre>
-<html  xmlns:my="http://mydomain.com">
-</pre>
+        <html xmlns:my="http://mydomain.com">
 
 
 # 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.
-
+The angular script creates a single global variable `angular` in the global namespace. All APIs
+are bound to fields of this global object.

docs/guide.building.ngdoc

@@ -0,0 +1,42 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Building Angular Apps
+@description
+
+
+# Bootstrapping Angular
+	## Bootstrap Automatically
+	## Bootstrap Manually
+# Working With Angular Templates
+## Expressions
+## Directives (and widgets, markup)
+## CSS
+# Working With the Data Model
+## Creating a Data Model
+### Implicit
+### Explicit
+## Server Communications
+### $xhr
+### $resource
+# Working With Controllers
+## Creating
+### Declaring
+### Coding in JavaScript
+### Instantiating
+## Using DI With Controllers
+### Declaring dependencies for the Injector
+# Working With Angular Services
+## Using DI With Services
+## Creating / Registering a service
+## Instantiating 
+## Built-in Services
+### List, Describe, Examples, Links to API
+## Writing Your Own Services
+# Working With Advanced Dependency Injection
+## Inferring dependencies from the signature of the factory function or constructor
+## "Currying" of arguments
+# Extending the Angular HTML Compiler
+## Extension points (widgets, directives, markup, filters)
+## The apis
+## How to create custom extensions
+## How to test all of these custom extensions