docs(guide/controller): reorganize, add Controller suffix, formatting

1 files changed, 39 insertions, 41 deletions

diff --git a/docs/content/guide/controller.ngdoc b/docs/content/guide/controller.ngdoc
index 6a75f090..5631d746 100644
--- a/docs/content/guide/controller.ngdoc
+++ b/docs/content/guide/controller.ngdoc
@@ -4,19 +4,31 @@
 
 # Understanding Controllers
 
-In Angular, a Controller is a JavaScript **constructor function** that is used to augment the 
+In Angular, a Controller is a JavaScript **constructor function** that is used to augment the
 {@link scope Angular Scope}.
 
 When a Controller is attached to the DOM via the {@link ng.directive:ngController ng-controller}
 directive, Angular will instantiate a new Controller object, using the specified Controller's
-**constructor function**.  A new **child scope** will be available as an injectable parameter to the
+**constructor function**. A new **child scope** will be available as an injectable parameter to the
 Controller's constructor function as `$scope`.
 
-Use Controllers to:
+Use controllers to:
 
 - Set up the initial state of the `$scope` object.
 - Add behavior to the `$scope` object.
 
+Do not use controllers to:
+
+- Manipulate DOM — Controllers should contain only business logic.
+  Putting any presentation logic into Controllers significantly affects its testability. Angular
+  has {@link databinding databinding} for most cases and {@link guide/directive directives} to
+  encapsulate manual DOM manipulation.
+- Format input — Use {@link forms angular form controls} instead.
+- Filter output — Use {@link guide/filter angular filters} instead.
+- Share code or state across controllers — Use {@link services angular
+services} instead.
+- Manage the life-cycle of other components (for example, to create service instances).
+
 # Setting up the initial state of a `$scope` object
 
 Typically, when you create an application you need to set up the initial state for the Angular
@@ -25,22 +37,22 @@ The properties contain the **view model** (the model that will be presented by t
 `$scope` properties will be available to the template at the point in the DOM where the Controller
 is registered.
 
-The following example shows a very simple constructor function for a Controller, `GreetingCtrl`,
+The following example shows a very simple constructor function for a Controller, `GreetingController`,
 which attaches a `greeting` property containing the string `'Hola!'` to the `$scope`:
 
 ```js
-    function GreetingCtrl($scope) {
-        $scope.greeting = 'Hola!';
-    }
+function GreetingController($scope) {
+  $scope.greeting = 'Hola!';
+}
 ```
 
 Once the Controller has been attached to the DOM, the `greeting` property can be data-bound to the
 template:
 
 ```js
-    <div ng-controller="GreetingCtrl">
-      {{ greeting }}
-    </div>
+<div ng-controller="GreetingController">
+  {{ greeting }}
+</div>
 ```
 
 **NOTE**: Although Angular allows you to create Controller functions in the global scope, this is
@@ -48,15 +60,15 @@ not recommended.  In a real application you should use the `.controller` method
 {@link module Angular Module} for your application as follows:
 
 ```js
-    var myApp = angular.module('myApp',[]);
+var myApp = angular.module('myApp',[]);
 
-    myApp.controller('GreetingCtrl', ['$scope', function($scope) {
-        $scope.greeting = 'Hola!';
-    }]);
+myApp.controller('GreetingController', ['$scope', function($scope) {
+  $scope.greeting = 'Hola!';
+}]);
 ```
 
 We have used an **inline injection annotation** to explicitly specify the dependency
-of the Controller on the `$scope` service provided by Angular. See the guide on 
+of the Controller on the `$scope` service provided by Angular. See the guide on
 [Dependency Injection](http://docs.angularjs.org/guide/di) for more information.
 
 
@@ -69,20 +81,20 @@ then available to be called from the template/view.
 The following example uses a Controller to add a method to the scope, which doubles a number:
 
 ```js
-    var myApp = angular.module('myApp',[]);
+var myApp = angular.module('myApp',[]);
 
-    myApp.controller('DoubleCtrl', ['$scope', function($scope) {
-        $scope.double = function(value) { return value * 2; };
-    }]);
+myApp.controller('DoubleController', ['$scope', function($scope) {
+  $scope.double = function(value) { return value * 2; };
+}]);
 ```
 
 Once the Controller has been attached to the DOM, the `double` method can be invoked in an Angular
 expression in the template:
 
 ```js
-    <div ng-controller="DoubleCtrl">
-      Two times <input ng-model="num"> equals {{ double(num) }}
-    </div>
+<div ng-controller="DoubleController">
+  Two times <input ng-model="num"> equals {{ double(num) }}
+</div>
 ```
 
 As discussed in the {@link concepts Concepts} section of this guide, any
@@ -97,23 +109,9 @@ needed for a single view.
 
 The most common way to keep Controllers slim is by encapsulating work that doesn't belong to
 controllers into services and then using these services in Controllers via dependency injection.
-This is discussed in the {@link di Dependency Injection} {@link dev_guide.services
+This is discussed in the {@link di Dependency Injection} {@link services
 Services} sections of this guide.
 
-Do not use Controllers for:
-
-- Any kind of DOM manipulation — Controllers should contain only business logic. DOM
-manipulation (the presentation logic of an application) is well known for being hard to test.
-Putting any presentation logic into Controllers significantly affects testability of the business
-logic. Angular offers {@link databinding databinding} for automatic DOM manipulation. If
-you have to perform your own manual DOM manipulation, encapsulate the presentation logic in
-{@link guide/directive directives}.
-- Input formatting — Use {@link forms angular form controls} instead.
-- Output filtering — Use {@link guide/filter angular filters} instead.
-- Sharing stateless or stateful code across Controllers — Use {@link dev_guide.services angular
-services} instead.
-- Managing the life-cycle of other components (for example, to create service instances).
-
 
 # Associating Controllers with Angular Scope Objects
 
@@ -147,11 +145,11 @@ string "very". Depending on which button is clicked, the `spice` model is set to
 
     myApp.controller('SpicyCtrl', ['$scope', function($scope){
         $scope.spice = 'very';
-        
+
         $scope.chiliSpicy = function() {
             $scope.spice = 'chili';
         };
-        
+
         $scope.jalapenoSpicy = function() {
             $scope.spice = 'jalapeño';
         };
@@ -190,7 +188,7 @@ previous example.
     myApp.controller('SpicyCtrl', ['$scope', function($scope){
         $scope.customSpice = "wasabi";
         $scope.spice = 'very';
-        
+
         $scope.spicy = function(spice){
             $scope.spice = spice;
         };
@@ -205,7 +203,7 @@ input box) in the second button.
 
 ## Scope Inheritance Example
 
-It is common to attach Controllers at different levels of the DOM hierarchy.  Since the 
+It is common to attach Controllers at different levels of the DOM hierarchy.  Since the
 {@link ng.directive:ngController ng-controller} directive creates a new child scope, we get a
 hierarchy of scopes that inherit from each other.  The `$scope` that each Controller receives will
 have access to properties and methods defined by Controllers higher up the hierarchy.