From 3b8b0eb1fb17114eed67b4543b18149b6efe6fec Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin
Date: Thu, 19 Sep 2013 12:48:06 +0100
Subject: docs(guide/services): rewording of explanation

---
 ...dev_guide.services.understanding_services.ngdoc | 59 ++++++++++++++--------
 1 file changed, 38 insertions(+), 21 deletions(-)

(limited to 'docs')

diff --git a/docs/content/guide/dev_guide.services.understanding_services.ngdoc b/docs/content/guide/dev_guide.services.understanding_services.ngdoc
index fb987c8a..be1966f6 100644
--- a/docs/content/guide/dev_guide.services.understanding_services.ngdoc
+++ b/docs/content/guide/dev_guide.services.understanding_services.ngdoc
@@ -2,33 +2,50 @@
 @name Developer Guide: Angular Services: Understanding Angular Services
 @description
 
-Angular services are singletons that carry out specific tasks common to web apps, such as the
-{@link api/ng.$http $http service} that provides low level access to the browser's
-`XMLHttpRequest` object.
+## What are Angular Services?
 
-To use an Angular service, you identify it as a dependency for the dependent (a controller, or
-another service) that depends on the service.  Angular's dependency injection subsystem takes care
-of the rest. The Angular injector subsystem is in charge of service instantiation, resolution of
-dependencies, and provision of dependencies to factory functions as requested.
+Angular services are singletons objects or functions that carry out specific tasks common to web apps.
+Angular has a number of built in services, such as the {@link api/ng.$http $http service}, which
+provides access to the browser's `XMLHttpRequest` object for making requests to a server. Like other core
+Angular variables and identifiers, the built-in services always start with `$` (such as `$http` mentioned
+above). You can also create your own custom services.
 
-The purpose of a service factory function is to generate a single object or function that 
-represents the service to the rest of the application. That object or function will then be
-passed as a parameter to any other factory function which specifies a dependency on this service.
+## Using a Service
 
-Angular factory functions are executed lazily. That is, they are only executed when needed 
-to satisfy a dependency, and are then executed exactly once for each service. Everything which is
-dependent on this service gets a reference to the single instance generated by the service factory.
+To use an Angular service, you identify it as a dependency for the component (controller, service,
+filter or directive) that depends on the service.  Angular's dependency injection subsystem takes
+care of the rest. The Angular injector subsystem is in charge of service instantiation, resolution
+of dependencies, and provision of dependencies to components as requested.
 
-Angular injects dependencies using "constructor" injection (the service is passed in via a factory
-function). Because JavaScript is a dynamically typed language, Angular's dependency injection
-subsystem cannot use static types to identify service dependencies. For this reason a dependent
-must explicitly define its dependencies by using the `$inject` property.  For example:
+Angular injects dependencies using
+{@link http://misko.hevery.com/2009/02/19/constructor-injection-vs-setter-injection/ "constructor" injection}.
+The dependency is passed to the component's factory/constructor function. Because JavaScript is a dynamically
+typed language, Angular's dependency injection subsystem cannot use static types to identify service
+dependencies. For this reason a component must, explicitly, define its dependencies by using one of the
+{@link di injection annotation} methods.  For example, by providing a `$inject` property:
 
-        myController.$inject = ['$location'];
+        var MyController = function($location) { ... };
+        MyController.$inject = ['$location'];
+        myModule.controller('MyController', MyController);
 
-The Angular web framework provides a set of services for common operations. Like other core Angular
-variables and identifiers, the built-in services always start with `$` (such as `$http` mentioned
-above). You can also create your own custom services.
+Or by providing an "inline" injection annotation:
+
+        var myService = function($http) { ... };
+        myModule.factory('myService', ['$http', myService]);
+
+## Defining a Service
+
+Application developers are free to define their own services by registering a their name, and **service
+factory function**, in Angular modules.
+
+The purpose of the **service factory function** is to generate the single object, or function, that 
+represents the service to the rest of the application. That object, or function, will then be
+injected into any component (controller, service, filter or directive) that specifies a dependency
+on the service.
+
+Angular factory functions are executed lazily. That is, they are only executed when needed 
+to satisfy a dependency, and are then executed exactly once for each service. Everything that is
+dependent on this service gets a reference to the single instance generated by the service factory.
 
 ## Related Topics
 
-- 
cgit v1.2.3