new batch of docs

docs/content/guide/dev_guide.services.creating_services.ngdoc

@@ -0,0 +1,71 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Angular Services: Creating Angular Services
+@description
+
+
+While angular offers several useful services, for any nontrivial application you'll find it useful
+to write your own custom services. To do this you begin by registering a service factory function
+that angular's DI will use to create the service object when it is needed.
+
+
+The `angular.service` method accepts three parameters:
+
+
+- `{string} name` - Name of the service.
+- `{function()} factory` - Factory function (called just once by DI).
+- `{Object} config` -  Configuration object with the following properties:
+  - `$inject` - {Array.<string>} - Array of service ids this service depends on. These services
+will be passed as arguments into the factory function in the same order specified in the `$inject`
+array. Defaults to `[]`.
+  - `$eager` - {boolean} - If true, the service factory will be called and the service will be
+instantiated when angular boots. If false, the 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.
+
+
+All angular services participate in {@link dev_guide.di 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.
+
+
+Following is an example of a very simple service. This service depends on the `$window` service
+(which is passed as a parameter to the factory function) and is just a function. The service simply
+stores all notifications; after the third one, the service displays all of the notifications 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>
+
+
+
+
+## Related Topics
+
+
+* {@link dev_guide.services.understanding_services Understanding Angular Services}
+* {@link dev_guide.services.registering_services Registering Angular Services}
+* {@link dev_guide.services.managing_dependencies Managing Service Dependencies}
+* {@link dev_guide.services.injecting_controllers Injecting Services Into Controllers }
+* {@link dev_guide.services.testing_services Testing Angular Services}
+
+
+## Related API
+
+
+* {@link api/angular.service Angular Service API}