yet another docs batch

6 files changed, 27 insertions, 352 deletions

diff --git a/docs/content/api/angular.attrMarkup.ngdoc b/docs/content/api/angular.attrMarkup.ngdoc
deleted file mode 100644
index aad20866..00000000
--- a/docs/content/api/angular.attrMarkup.ngdoc
+++ /dev/null
@@ -1,15 +0,0 @@
-@workInProgress
-@ngdoc overview
-@name angular.attrMarkup
-
-@description
-Attribute markup extends the angular compiler in a very similar way as {@link angular.markup} except
-that it allows you to modify the state of the attribute text rather then the content of a node.
-
-<pre>
-angular.attrMarkup('extraClass', function(attrValue, attrName, element){
-  if (attrName == 'additional-class') {
-    element.addClass(attrValue);
-  }
-});
-</pre>
diff --git a/docs/content/api/angular.directive.ngdoc b/docs/content/api/angular.directive.ngdoc
deleted file mode 100644
index 277830b9..00000000
--- a/docs/content/api/angular.directive.ngdoc
+++ /dev/null
@@ -1,53 +0,0 @@
-@workInProgress
-@ngdoc overview
-@name angular.directive
-@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.
-
-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.
-
-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);
-      });
-    };
-  });
-</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.
-
-For example, consider this piece of HTML, which uses the `ng:repeat`, `ng:init`,
-and `ng:bind` widget and directives:
-<pre>
-  <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.widget.@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.
diff --git a/docs/content/api/angular.element.ngdoc b/docs/content/api/angular.element.ngdoc
deleted file mode 100644
index 2ce007fd..00000000
--- a/docs/content/api/angular.element.ngdoc
+++ /dev/null
@@ -1,49 +0,0 @@
-@workInProgress
-@ngdoc function
-@name angular.element
-@function
-
-@description
-Wraps a raw DOM element or HTML string as [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.
-
-Real jQuery always takes precedence (as long as it was loaded before `DOMContentEvent`)
-
-Angular's jQuery lite implementation is a tiny API-compatible subset of jQuery which allows
-angular to manipulate DOM. The jQuery lite implements only a subset of jQuery api, with the
-focus on the most commonly needed functionality and minimal footprint. For this reason only a
-limited number of jQuery methods, arguments and invocation styles are supported.
-
-NOTE: All element references in angular are always wrapped with jQuery (lite) and are never
-raw DOM references.
-
-## Angular's jQuery lite implements these functions:
-
-- [addClass()](http://api.jquery.com/addClass/)
-- [after()](http://api.jquery.com/after/)
-- [append()](http://api.jquery.com/append/)
-- [attr()](http://api.jquery.com/attr/)
-- [bind()](http://api.jquery.com/bind/)
-- [children()](http://api.jquery.com/children/)
-- [clone()](http://api.jquery.com/clone/)
-- [css()](http://api.jquery.com/css/)
-- [data()](http://api.jquery.com/data/)
-- [hasClass()](http://api.jquery.com/hasClass/)
-- [parent()](http://api.jquery.com/parent/)
-- [remove()](http://api.jquery.com/remove/)
-- [removeAttr()](http://api.jquery.com/removeAttr/)
-- [removeClass()](http://api.jquery.com/removeClass/)
-- [removeData()](http://api.jquery.com/removeData/)
-- [replaceWith()](http://api.jquery.com/replaceWith/)
-- [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:
-
-- `scope()` - retrieves the current angular scope of the element.
-
-@param {string|DOMElement} element HTML string or DOMElement to be wrapped into jQuery.
-@returns {Object} jQuery object.
diff --git a/docs/content/api/angular.markup.ngdoc b/docs/content/api/angular.markup.ngdoc
deleted file mode 100644
index a40385c8..00000000
--- a/docs/content/api/angular.markup.ngdoc
+++ /dev/null
@@ -1,66 +0,0 @@
-@workInProgress
-@ngdoc overview
-@name angular.markup
-
-@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}.
-
-#`{{}}` (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
-
-<pre>
-{{expression}}
-</pre>
-
-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
-expanded elements are then {@link guide.compiler compiled} normally.
-
-# Custom markup
-Let's say you want to define this shorthand for a horizontal rule: `---` for `<hr/>`.
-
-In other words, this HTML:
-<pre>
-header
----
-footer
-</pre>
-
-should translate to:
-<pre>
-header
-<hr/>
-footer
-</pre>
-
-Here's how the angular compiler could be extended to achieve this:
-<pre>
-angular.markup('---', function(text, textNode, parentElement) {
-  var compiler = this;
-  var index = text.indexOf('---');
-  if (index > -1) {
-    var before = compiler.text(text.substring(0, index));
-    var hr = compiler.element('hr');
-    var after = compiler.text(text.substring(index + 3));
-    textNode.after(after);
-    textNode.after(hr);
-    textNode.after(before);
-    textNode.remove();
-  }
-});
-</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.
diff --git a/docs/content/api/angular.service.ngdoc b/docs/content/api/angular.service.ngdoc
index 0d3406e5..9a191921 100644
--- a/docs/content/api/angular.service.ngdoc
+++ b/docs/content/api/angular.service.ngdoc
@@ -1,175 +1,32 @@
 @workInProgress
 @ngdoc overview
 @name angular.service
-
 @description
-# Overview
-Services are substituable objects, which are wired together using dependency injection (DI).
-Each service could have dependencies (other services), which are passed in constructor.
-Because JS is dynamicaly typed language, dependency injection can not use static types
-to identify these dependencies, so each service must explicitely define its dependencies.
-This is done by `$inject` property.
-
-
-# Built-in services
-angular provides a set of services for common operations. These services can be overriden by custom
-services if needed.
-
-Like other core angular variables and identifiers, the built-in services always start with `$`.
-
-  * {@link angular.service.$browser $browser}
-  * {@link angular.service.$window $window}
-  * {@link angular.service.$document $document}
-  * {@link angular.service.$location $location}
-  * {@link angular.service.$log $log}
-  * {@link angular.service.$exceptionHandler $exceptionHandler}
-  * {@link angular.service.$hover $hover}
-  * {@link angular.service.$invalidWidgets $invalidWidgets}
-  * {@link angular.service.$route $route}
-  * {@link angular.service.$xhr $xhr}
-  * {@link angular.service.$xhr.error $xhr.error}
-  * {@link angular.service.$xhr.bulk $xhr.bulk}
-  * {@link angular.service.$xhr.cache $xhr.cache}
-  * {@link angular.service.$resource $resource}
-  * {@link angular.service.$cookies $cookies}
-  * {@link angular.service.$cookieStore $cookieStore}
-
-# Writing your own custom services
-angular provides only set of basic services, so for any nontrivial application it will be necessary
-to write one or more custom services. To do so, a factory function that creates a services needs to
-be registered with angular's dependency injector. This factory function must return an object - the
-service (it is not called with the `new` operator).
-
-**angular.service** accepts three parameters:
-
-  - `{string} name` - Name of the service.
-  - `{function()} factory` - Factory function (called just once by DI).
-  - `{Object} config` -  Configuration object with following properties:
-    - `$inject` - {Array.<string>} - Array of service ids that this service depends on. These
-      services will be passed as arguments into the factory function in the same order as specified
-      in the `$inject` array. Defaults to `[]`.
-    - `$eager` - {boolean} - If true, the service factory will be called and thus, the service will
-      be instantiated when angular boots. If false, service will be lazily instantiated when it is
-      first requested during instantiation of a dependant. Defaults to `false`.
-
-The `this` of the factory function is bound to the root scope of the angular application.
-
-angular enables services to participate in dependency injection (DI) by registering themselves with
-angular's DI system (injector) under a `name` (id) as well as by declaring dependencies which need
-to be provided for the factory function of the registered service. The ability to swap dependencies
-for mocks/stubs/dummies in tests allows for services to be highly testable.
-
-Here is an example of very simple service. This service requires $window service (it's
-passed as a parameter to factory function) and it's just a function.
-
-This service simple stores all notifications and after third one, it displays all of them by
-window alert.
-<pre>
-       angular.service('notify', function(win) {
-         var msgs = [];
-         return function(msg) {
-           msgs.push(msg);
-           if (msgs.length == 3) {
-             win.alert(msgs.join("\n"));
-             msgs = [];
-           }
-         };
-       }, {$inject: ['$window']});
-</pre>
-
-And here is a unit test for this service. We use Jasmine spy (mock) instead of real browser's alert.
-<pre>
-var mock, notify;
-
-beforeEach(function() {
-  mock = {alert: jasmine.createSpy()};
-  notify = angular.service('notify')(mock);
-});
-
-it('should not alert first two notifications', function() {
-  notify('one');
-  notify('two');
-  expect(mock.alert).not.toHaveBeenCalled();
-});
-
-it('should alert all after third notification', function() {
-  notify('one');
-  notify('two');
-  notify('three');
-  expect(mock.alert).toHaveBeenCalledWith("one\ntwo\nthree");
-});
-
-it('should clear messages after alert', function() {
-  notify('one');
-  notify('two');
-  notify('third');
-  notify('more');
-  notify('two');
-  notify('third');
-  expect(mock.alert.callCount).toEqual(2);
-  expect(mock.alert.mostRecentCall.args).toEqual(["more\ntwo\nthird"]);
-});
-</pre>
-
-# Injecting services into controllers
-Using services as dependencies for controllers is very similar to using them as dependencies for
-another service.
-
-JavaScript is dynamic language, so DI is not able to figure out which services to inject by
-static types (like in static typed languages). Therefore you must specify the service name
-by the `$inject` property - it's an array that contains strings with names of services to be
-injected. The name must match the id that service has been registered as with angular.
-The order of the services in the array matters, because this order will be used when calling
-the factory function with injected parameters. The names of parameters in factory function
-don't matter, but by convention they match the service ids.
-<pre>
-function myController($loc, $log) {
-  this.firstMethod = function() {
-    // use $location service
-    $loc.setHash();
-  };
-  this.secondMethod = function() {
-    // use $log service
-    $log.info('...');
-  };
-}
-// which services to inject ?
-myController.$inject = ['$location', '$log'];
-</pre>
-
-@example
-<doc:example>
- <doc:source>
-  <script type="text/javascript">
-   angular.service('notify', function(win) {
-     var msgs = [];
-     return function(msg) {
-       msgs.push(msg);
-       if (msgs.length == 3) {
-         win.alert(msgs.join("\n"));
-         msgs = [];
-       }
-     };
-   }, {$inject: ['$window']});
-
-   function myController(notifyService) {
-     this.callNotify = function(msg) {
-       notifyService(msg);
-     };
-   }
 
-   myController.$inject = ['notify'];
-  </script>
 
-  <div ng:controller="myController">
-  <p>Let's try this simple notify service, injected into the controller...</p>
-  <input ng:init="message='test'" type="text" name="message" />
-  <button ng:click="callNotify(message);">NOTIFY</button>
-  </div>
- </doc:source>
- <doc:scenario>
-   it('should test service', function(){
-     expect(element(':input[name=message]').val()).toEqual('test');
-   });
- </doc:scenario>
-</doc:example>
+The services API provides objects for carrying out common web app tasks.  Service objects are
+managed by angular's {@link guide/dev_guide.di dependency injection system}.
+
+
+* {@link angular.service.$browser $browser } - Provides an instance of a browser object
+* {@link angular.service.$cookieStore $cookieStore } - Provides key / value storage backed by
+session cookies
+* {@link angular.service.$cookies $cookies } - Provides read / write access to browser cookies
+* {@link angular.service.$defer $defer } - Defers function execution and try / catch block
+* {@link angular.service.$document $document } - Provides reference to `window.document` element
+* {@link angular.service.$exceptionHandler $exceptionHandler } - Receives uncaught angular
+exceptions
+* {@link angular.service.$hover $hover } -
+* {@link angular.service.$invalidWidgets $invalidWidgets } - Holds references to invalid widgets
+* {@link angular.service.$location $location } - Parses the browser location URL
+* {@link angular.service.$log $log } - Provides logging service
+* {@link angular.service.$resource $resource } - Creates objects for interacting with RESTful
+server-side data sources
+* {@link angular.service.$route $route } - Provides deep-linking services
+* {@link angular.service.$updateView $updateView } - Queues view updates
+* {@link angular.service.$window $window } - References the browsers `window` object
+* {@link angular.service.$xhr $xhr} - Generates an XHR request.
+
+
+For information on how angular services work and how to write your own services, see {@link
+guide/dev_guide.services Angular Services} in the angular Developer Guide.
diff --git a/docs/content/api/index.ngdoc b/docs/content/api/index.ngdoc
index 9bf34314..d604fd17 100644
--- a/docs/content/api/index.ngdoc
+++ b/docs/content/api/index.ngdoc
@@ -8,6 +8,7 @@
 
 * {@link angular.widget Widgets} - Angular custom DOM element
 * {@link angular.directive Directives} - Angular DOM element attributes
+* {@link angular.markup Markup} and {@link angular.attrMarkup Attribute Markup}
 * {@link angular.filter Filters} - Angular output filters
 * {@link angular.formatter Formatters} - Angular converters for form elements
 * {@link angular.validator Validators} - Angular input validators