fixup 1

gkalpak · gkalpak · commit 2549951053c6 · 2016-05-24T14:00:39.000+03:00
- Fix typos.
- Improve wording.
- Simplify links.
- Add warnings:
  - Firewalls blocking `git:`.
  - File include order (i.e. `.module` files before other files).
- Improve tests:
  - Remove unnecessary locals when calling `$componentController()`.
  - Extract protractor queries.
diff --git a/docs/content/tutorial/index.ngdoc b/docs/content/tutorial/index.ngdoc
@@ -96,6 +96,19 @@ cd angular-phonecat
 The tutorial instructions, from now on, assume you are running all commands from within the
 `angular-phonecat` directory.
 
+<div class="alert alert-warning">
+  <p>
+    `git` and other tools (for example `bower` - see below), often use the `git:` protocol for
+    accessing files in remote repositories. Some firewall configurations are blocking `git://` URLs,
+    which leads to errors when trying to clone repositories or download dependencies. (For example
+    corporate firewalls are "notorious" for blocking `git:`.)
+  </p>
+  <p>
+    If you run into this issue, you can force the use of `https:` instead, by running the following
+    command: `git config --global url."https://".insteadOf git://`
+  </p>
+</div>
+
 
 ### Install Node.js
 
@@ -257,7 +270,7 @@ npm run update-webdriver
   the [Java Development Kit (JDK)][jdk] to be installed on your local machine. Check this
   by running `java -version` from the command line.
 
-  If JDK is not already install, you can download it [here][jdk-download].
+  If JDK is not already installed, you can download it [here][jdk-download].
 </div>
 
 Since Protractor works by interacting with a running application, we need to start our web server:
diff --git a/docs/content/tutorial/step_00.ngdoc b/docs/content/tutorial/step_00.ngdoc
@@ -79,7 +79,7 @@ directive is used to flag the HTML element that Angular should consider to be th
 our application. This gives application developers the freedom to tell Angular if the entire HTML
 page or only a portion of it should be treated as the AngularJS application.
 
-For more info on `ngApp`, check out the {@link ng.directive:ngApp API Reference}.
+For more info on `ngApp`, check out the {@link ngApp API Reference}.
 
 <br />
 **`angular.js` script tag:**
@@ -90,9 +90,9 @@ For more info on `ngApp`, check out the {@link ng.directive:ngApp API Reference}
 
 This code downloads the `angular.js` script which registers a callback that will be executed by the
 browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
-looks for the {@link ng.directive:ngApp ngApp} directive. If Angular finds the directive, it will
-bootstrap the application with the root of the application DOM being the element on which the
-`ngApp` directive was defined.
+looks for the {@link ngApp ngApp} directive. If Angular finds the directive, it will bootstrap the
+application with the root of the application DOM being the element on which the `ngApp` directive
+was defined.
 
 For more info on bootstrapping your app, checkout the [Bootstrap](guide/bootstrap) section of the
 Developer Guide.
diff --git a/docs/content/tutorial/step_02.ngdoc b/docs/content/tutorial/step_02.ngdoc
@@ -50,17 +50,17 @@ The view is constructed by Angular from this template.
 </html>
 ```
 
-We replaced the hard-coded phone list with the {@link ng.directive:ngRepeat ngRepeat} directive and
-two {@link guide/expression Angular expressions}:
+We replaced the hard-coded phone list with the {@link ngRepeat ngRepeat} directive and two
+{@link guide/expression Angular expressions}:
 
 * The `ng-repeat="phone in phones"` attribute on the `<li>` tag is an Angular repeater directive.
   The repeater tells Angular to create a `<li>` element for each phone in the list, using the `<li>`
   tag as the template.
 * The expressions wrapped in curly braces (`{{phone.name}}` and `{{phone.snippet}}`) will be
   replaced by the values of the expressions.
 
-We have also added a new directive, called {@link ng.directive:ngController ngController}, which
-attaches a `PhoneListController` **controller** to the `<body>` tag. At this point:
+We have also added a new directive, called {@link ngController ngController}, which attaches a
+`PhoneListController` **controller** to the `<body>` tag. At this point:
 
 * `PhoneListController` is in charge of the DOM sub-tree under (and including) the `<body>` element.
 * The expressions in curly braces (`{{phone.name}}` and `{{phone.snippet}}`) denote bindings, which
@@ -112,9 +112,8 @@ Although the controller is not yet doing very much, it plays a crucial role. By
 for our data model, the controller allows us to establish data-binding between the model and the
 view. We connected the dots between the presentation, data, and logic components as follows:
 
-* The {@link ng.directive:ngController ngController} directive, located on the `<body>` tag,
-  references the name of our controller, `PhoneListController` (located in the JavaScript file
-  `app.js`).
+* The {@link ngController ngController} directive, located on the `<body>` tag, references the name
+  of our controller, `PhoneListController` (located in the JavaScript file `app.js`).
 
 * The `PhoneListController` controller attaches the phone data to the `$scope` that was injected
   into our controller function. This _scope_ is a prototypal descendant of the _root scope_ that was
diff --git a/docs/content/tutorial/step_03.ngdoc b/docs/content/tutorial/step_03.ngdoc
@@ -64,8 +64,9 @@ application or vice versa.
   </p>
 </div>
 
-To create a component, we use the `.component()` method of an {@link module Angular module}. We must
-provide the name of the component and the Component Definition Object (CDO for short).
+To create a component, we use the {@link angular.Module#component .component()} method of an
+{@link module Angular module}. We must provide the name of the component and the Component
+Definition Object (CDO for short).
 
 Remember that (since components are also directives) the name of the component is in `camelCase`,
 but we will use `kebab-case`, when referring to it in our HTML.
@@ -100,8 +101,7 @@ inside the controller constructor), instead of directly to the scope.
 
 From the template, we can refer to our controller instance using an alias. This way, the context of
 evaluation for our expressions is even more clear. By default, components use `$ctrl` as the
-controller alias, but we can override it, should the need arise. (It is a very uncommon need though,
-so we will be sticking with `$ctrl` most of the time.)
+controller alias, but we can override it, should the need arise.
 
 There are more options available, so make sure you check out the
 {@link ng.$compileProvider#component API Reference}, before using `.component()` in your own
@@ -223,7 +223,7 @@ describe('phoneList', function() {
   describe('PhoneListController', function() {
 
     it('should create a `phones` model with 3 phones', inject(function($componentController) {
-      var ctrl = $componentController('phoneList', {$scope: {}});
+      var ctrl = $componentController('phoneList');
 
       expect(ctrl.phones.length).toBe(3);
     }));
diff --git a/docs/content/tutorial/step_04.ngdoc b/docs/content/tutorial/step_04.ngdoc
@@ -53,7 +53,7 @@ We will keep this in mind though, as we add more features.
 
 So, now that we learned we should put everything in its own file, our `app/` directory will soon be
 full with dozens of files and specs (remember we keep our unit test files next to the corresponding
-source code files). What's more important, logically related files will not be groupped together; it
+source code files). What's more important, logically related files will not be grouped together; it
 will be really difficult of locate all files related to a specific section of the application and
 make a change or fix a bug.
 
@@ -66,8 +66,8 @@ parts of the application. We will put those inside `app/core/`.
 
 <div class="alert alert-info">
   <p>
-    Other typical names for our `core` directory are `common` and `components`. The latter is kind
-    of misleading though, as it will contain other things than components as well.
+    Other typical names for our `core` directory are `shared`, `common` and `components`. The last
+    one is kind of misleading though, as it will contain other things than components as well.
   </p>
   <p>
     (This is mostly a relic of the past, when "components" just meant the generic building blocks of
@@ -90,7 +90,7 @@ Based on what we have discussed so far, here is our directory/file layout for th
 ## Using Modules
 
 As previously mentioned, one of the benefits of having a modular architecture is code reuse &mdash;
-not only inside the same application, but across application too. There is one final step in making
+not only inside the same application, but across applications too. There is one final step in making
 this code reuse frictionless:
 
 * Each feature/section should declare its own module and all related entities should register
@@ -175,11 +175,16 @@ will make all entities registered on `phoneList` available on `phonecatApp` as w
     we have created. This might seem tedious, but is totally worth it.
   </p>
   <p>
-    In a production-ready application, you are better off concatenating and minifying all your
-    JavaScript files anyway (for performance reasons), so this won't be an issue any more.
+    In a production-ready application, you would concatenate and minify all your JavaScript files
+    anyway (for performance reasons), so this won't be an issue any more.
   </p>
 </div>
 
+<div class="alert alert-warning">
+  Note that files defining a module (i.e. `.module.js`) need to be included before other files that
+  add features (e.g. components, controllers, services, filters) to that module. 
+</div>
+
 
 ## External Templates
 
@@ -193,7 +198,7 @@ IDE/editor has to offer (e.g. HTML-specific color-highlighting and auto-completi
 our component definitions cleaner.
 
 So, while it's perfectly fine to keep our component templates inline (using the `template` property
-of the CDO), we decided to use an external template for our `phoneList` component. In order to
+of the CDO), we are going to use an external template for our `phoneList` component. In order to
 denote that we are using an external template, we use the `templateUrl` property and specify the URL
 that our template will be loaded from. Since we want to keep our template close to where the
 component is defined, we place it inside `app/phone-list/`.
@@ -242,7 +247,7 @@ HTTP request to get the template from `app/phone-list/phone-list.template.html`.
 
 ## Final Directory/File Layout
 
-After all the refactorings that took place, this is how our application looks like from the outside:
+After all the refactorings that took place, this is how our application looks from the outside:
 
 <br />
 **`/`:**
@@ -289,10 +294,10 @@ If not already done so, run the tests (using the `npm test` command) and verify
 pass.
 
 <div class="alert alert-success">
-  One of the great things about tests is the confidence the provide, when refactoring your
+  One of the great things about tests is the confidence they provide, when refactoring your
   application. It's easy to break something as you start moving files around and re-arranging
-  modules. Having a good test coverage is the quickest, easiest and most reliable way of knowing
-  that your application will continue to work as expected.
+  modules. Having good test coverage is the quickest, easiest and most reliable way of knowing that
+  your application will continue to work as expected.
 </div>
 
 
diff --git a/docs/content/tutorial/step_05.ngdoc b/docs/content/tutorial/step_05.ngdoc
@@ -52,13 +52,12 @@ We made no changes to the component's controller.
   </div>
 ```
 
-We added a standard HTML `<input>` tag and used Angular's
-{@link ng.filter:filter filter} function to process the input for the
-{@link ng.directive:ngRepeat ngRepeat} directive.
+We added a standard HTML `<input>` tag and used Angular's {@link ng.filter:filter filter} function
+to process the input for the {@link ngRepeat ngRepeat} directive.
 
-By virtue of the {@link ng.directive:ngModel ngModel} directive, this lets a user enter search
-criteria and immediately see the effects of their search on the phone list. This new code
-demonstrates the following:
+By virtue of the {@link ngModel ngModel} directive, this lets a user enter search criteria and
+immediately see the effects of their search on the phone list. This new code demonstrates the
+following:
 
 * Data-binding: This is one of the core features in Angular. When the page loads, Angular binds the
   value of the input box to the data model variable specified with `ngModel` and keeps the two in
@@ -83,8 +82,8 @@ demonstrates the following:
 
 In previous steps, we learned how to write and run unit tests. Unit tests are perfect for testing
 controllers and other parts of our application written in JavaScript, but they can't easily
-test DOM manipulation or the wiring of our application. For these, an end-to-end (E2E) test is a
-much better choice.
+test templates, DOM manipulation or interoperability of components and services. For these, an
+end-to-end (E2E) test is a much better choice.
 
 The search feature was fully implemented via templates and data-binding, so we'll write our first
 E2E test, to verify that the feature works.
@@ -132,13 +131,14 @@ Jasmine, the E2E test uses APIs of [Protractor][protractor]. Read about the Prot
 [Protractor API Docs][protractor-docs].
 
 Much like Karma is the test runner for unit tests, we use Protractor to run E2E tests. Try it with
-`npm run protractor`. E2E tests are slow, so unlike with unit tests, Protractor will exit after the
+`npm run protractor`. E2E tests take time, so unlike with unit tests, Protractor will exit after the
 tests run and will not automatically rerun the test suite on every file change.
 To rerun the test suite, execute `npm run protractor` again.
 
 <div class="alert alert-info">
-  **Note:** You must ensure your application is being served via a web server to test with
-  protractor. You can do this by using `npm start`.
+  **Note:** In order for protractor to access and run tests against your application, it must be
+  served via a web server. In a different terminal/command line window, run `npm start` to fire up
+  the web server.
 </div>
 
 
diff --git a/docs/content/tutorial/step_06.ngdoc b/docs/content/tutorial/step_06.ngdoc
@@ -64,9 +64,9 @@ We made the following changes to the `phone-list.template.html` template:
 
   <img class="diagram" src="img/tutorial/tutorial_06.png">
 
-* We then chained the `filter` filter with the {@link ng.filter:orderBy orderBy} filter to further
-  process the input for the repeater. `orderBy` is a filter that takes an input array, copies it and
-  reorders the copy which is then returned.
+* We then chained the `filter` filter with the {@link orderBy orderBy} filter to further process the
+  input for the repeater. `orderBy` is a filter that takes an input array, copies it and reorders
+  the copy which is then returned.
 
   Angular creates a two way data-binding between the select element and the `$ctrl.orderProp` model.
   `$ctrl.orderProp` is then used as the input for the `orderBy` filter.
@@ -143,7 +143,7 @@ describe('phoneList', function() {
     var ctrl;
 
     beforeEach(inject(function($componentController) {
-      ctrl = $componentController('phoneList', {$scope: {}});
+      ctrl = $componentController('phoneList');
     }));
 
     it('should create a `phones` model with 3 phones', function() {
@@ -183,23 +183,25 @@ Let's turn our attention to the E2E tests.
       ...
 
       it('should be possible to control phone order via the drop-down menu', function() {
+        var queryField = element(by.model('$ctrl.query'));
+        var orderSelect = element(by.model('$ctrl.orderProp'));
+        var nameOption = orderSelect.element(by.css('option[value="name"]'));
         var phoneNameColumn = element.all(by.repeater('phone in $ctrl.phones').column('phone.name'));
-        var query = element(by.model('$ctrl.query'));
 
         function getNames() {
           return phoneNameColumn.map(function(elem) {
             return elem.getText();
           });
         }
 
-        query.sendKeys('tablet'); // Let's narrow the dataset to make the test assertions shorter
+        queryField.sendKeys('tablet');   // Let's narrow the dataset to make the assertions shorter
 
         expect(getNames()).toEqual([
           'Motorola XOOM\u2122 with Wi-Fi',
           'MOTOROLA XOOM\u2122'
         ]);
 
-        element(by.model('$ctrl.orderProp')).element(by.css('option[value="name"]')).click();
+        nameOption.click();
 
         expect(getNames()).toEqual([
           'MOTOROLA XOOM\u2122',
diff --git a/docs/content/tutorial/step_07.ngdoc b/docs/content/tutorial/step_07.ngdoc
@@ -77,10 +77,10 @@ in this tutorial.)
 
 The `$http` service returns a {@link ng.$q promise object}, which has a `then()` method. We call
 this method to handle the asynchronous response and assign the phone data to the controller, as a
-model called `phones`. Notice that Angular detected the JSON response and parsed it for us into the
-`data` property of the `response` object passed to our callback!
+property called `phones`. Notice that Angular detected the JSON response and parsed it for us into 
+the `data` property of the `response` object passed to our callback!
 
-Since we are making the assignment of the `phones` model in a callback function, where the `this`
+Since we are making the assignment of the `phones` property in a callback function, where the `this`
 value is not defined, we also introduce a local variable called `self` that points back to the
 controller instance.
 
@@ -207,7 +207,7 @@ describe('phoneList', function() {
       $httpBackend.expectGET('phones/phones.json')
                   .respond([{name: 'Nexus S'}, {name: 'Motorola DROID'}]);
 
-      ctrl = $componentController('phoneList', {$scope: {}});
+      ctrl = $componentController('phoneList');
     }));
 
     ...
@@ -242,17 +242,18 @@ request from the controller. To do this we:
   {@link ngMock.$httpBackend mock version} of the service that in a production environment
   facilitates all XHR and JSONP requests. The mock version of this service allows us to write tests
   without having to deal with native APIs and the global state associated with them — both of which
-  make testing a nightmare.
+  make testing a nightmare. It also overcomes the asynchronous nature of these calls, which would
+  slow down unit tests.
 
 * Use the `$httpBackend.expectGET()` method to train the `$httpBackend` service to expect an
   incoming HTTP request and tell it what to respond with. Note that the responses are not returned
   until we call the `$httpBackend.flush()` method.
 
-Now we will make assertions to verify that the `phones` model doesn't exist on the controller before
-the response is received:
+Now we will make assertions to verify that the `phones` property doesn't exist on the controller 
+before the response is received:
 
 ```js
-    it('should create a `phones` model with 2 phones fetched with `$http`', function() {
+    it('should create a `phones` property with 2 phones fetched with `$http`', function() {
       expect(ctrl.phones).toBeUndefined();
 
       $httpBackend.flush();
@@ -265,12 +266,12 @@ the response is received:
   {@link ngMock.$httpBackend#flushing-http-requests Flushing HTTP requests} in the mock
   `$httpBackend` documentation for a full explanation of why this is necessary.
 
-* We make the assertions, verifying that the `phones` model now exists on the controller.
+* We make the assertions, verifying that the `phones` property now exists on the controller.
 
 Finally, we verify that the default value of `orderProp` is set correctly:
 
 ```js
-    it('should set a default value for the `orderProp` model', function() {
+    it('should set a default value for the `orderProp` property', function() {
       expect(ctrl.orderProp).toBe('age');
     });
 ```
diff --git a/docs/content/tutorial/step_08.ngdoc b/docs/content/tutorial/step_08.ngdoc
diff --git a/docs/content/tutorial/step_09.ngdoc b/docs/content/tutorial/step_09.ngdoc
diff --git a/docs/content/tutorial/step_10.ngdoc b/docs/content/tutorial/step_10.ngdoc
diff --git a/docs/content/tutorial/step_14.ngdoc b/docs/content/tutorial/step_14.ngdoc
