Merge branch 'pr-1055' into presubmit-master-pr-1055

docs/about/01-versioning.md

@@ -1,8 +1,8 @@
 Karma uses [Semantic Versioning] with a little exception:
-- even versions (eg. `0.6.x`, `0.8.x`) are considered stable - no breaking changes or new features, only bug fixes will pushed into this branch,
+- even versions (eg. `0.6.x`, `0.8.x`) are considered stable - no breaking changes or new features, only bug fixes will be pushed into this branch
 - odd versions (eg. `0.7.x`, `0.9.x`) are unstable - anything can happen ;-)
 
-Therefore it is recommended to rely on the latest stable version, which gives you automatic bug fixes, but does not break you:
+Therefore, it is recommended that you rely on the latest stable (even) version, which will give you automatic bug fixes, but will not break your test setup:
 ```javascript
 {
   "devDependencies": {

docs/about/03-migration.md

@@ -3,7 +3,7 @@ pageTitle: Migration from v0.10
 
 The good thing is that you don't have to migrate everything at once.
 You can leave all the existing projects using an older version of Karma and only use the latest
-version for the new projects. Or you can migrate the existing projects one at the time...
+version for the new projects. Alternatively, you can migrate the existing projects one at a time...
 
 
 Anyway, this migration should be easy ;-) so let's get started...
@@ -16,8 +16,9 @@ This will install the latest version of Karma and also update `package.json` of
 
 
 ## Install missing plugins
-Karma does not ship with any "default" plugin anymore.
-For existing projects, this should not cause any problems as NPM (when installing Karma 0.10) probably added these "default" plugins into `package.json` as regular dependencies.
+Karma does not ship with any "default" plugins anymore.
+For existing projects, this should not cause any problems as NPM (when updating Karma to 0.10 using
+`npm install karma --save-dev`) added these "default" plugins into `package.json` as regular dependencies.
 For new projects, just remember you have to install all the plugins you need. These are the "default" plugins that were removed:
 - karma-jasmine
 - karma-requirejs
@@ -33,7 +34,7 @@ For new projects, just remember you have to install all the plugins you need. Th
 Karma does not put the `karma` command in your system PATH anymore.
 If you want to use the `karma` command, please install the command line interface (`karma-cli`).
 
-You probably have `karma` package installed globally, in which case you should remove it first:
+You probably have the `karma` package installed globally, in which case you should remove it first:
 ```bash
 npm remove -g karma
 ```
@@ -45,11 +46,14 @@ npm install -g karma-cli
 
 
 ## Default configuration
-`autoWatch` is true by default, so if you don't wanna use it make sure you set it to `false`. But hey, give it a shot first, it's really awesome to run your tests on every save!
+`autoWatch` is true by default, so if you don't wanna use it make sure you set it to `false`.
+But hey, give it a shot first, it's really awesome to run your tests on every save!
 
 
 ## NPM complaining
-NPM is sometimes finicky so if you encounter errors such as "unsatisfied peer dependency", just try to remove all the packages (`rm -rf ./node_modules`) and install again.
+In some cases NPM can run into dependency tree issues during the migration process. If you are faced
+with an "unsatisfied peer dependency" error, removing all of the packages (`rm -rf ./node_modules`) and installing
+them again should clear up the issue.
 
 If you have any other issuses, please ask on the [mailing list].
 

docs/config/01-configuration-file.md

@@ -1,7 +1,7 @@
 ## Overview
 In order to serve you well, Karma needs to know about your project in order to test it
-and this is done via a configuration file. The easiest way to generate initial configuration file
-is using `karma init` command. This page lists all the available configuration options.
+and this is done via a configuration file. The easiest way to generate an initial configuration file
+is by using the `karma init` command. This page lists all of the available configuration options.
 
 Note: Most of the framework adapters, reporters, preprocessors and launchers needs to be loaded as [plugins].
 
@@ -31,9 +31,10 @@ module.exports = (config) ->
 ```
 
 ## File Patterns
-All of the configuration options which specify file paths use the [minimatch][minimatch] library to facilitate flexible but concise file expressions, so you can easily list all the files you want to include, along with excluding the files that need to be skipped.
+All of the configuration options, which specify file paths, use the [minimatch][minimatch] library to facilitate flexible
+but concise file expressions so you can easily list all of the files you want to include and exclude.
 
-You can find details of each option in the following section, but this is the list of options that utilize minimatch expressions:
+You can find details about each configuration option in the section below. The following options utilize minimatch expressions:
 
  * `exclude`
  * `files`
@@ -46,7 +47,7 @@ Examples:
  * `**/(foo|bar).js`: In all subdirectories, all "foo.js" or "bar.js" files
 
 ## Configuration Options
-These are all the available configuration options.
+These are all of the available configuration options.
 
 ## autoWatch
 **Type:** Boolean
@@ -55,8 +56,7 @@ These are all the available configuration options.
 
 **CLI:** `--auto-watch`, `--no-auto-watch`
 
-**Description:** Enable or disable watching files and executing the tests
-  whenever one of these files changes.
+**Description:** Enable or disable watching files and executing the tests whenever one of these files changes.
 
 
 ## autoWatchBatchDelay
@@ -87,7 +87,9 @@ relative path then it will be resolved to the `__dirname` of the configuration f
 
 **Description:** How long does Karma wait for a browser to reconnect (in ms).
 
-With a flaky connection it is pretty common that browser disconnects but the actual execution is running without any problems. Karma does not treat a disconnection as immediate failure and rather wait `browserDisconnectTimeout` ms. If the browser reconnect during that time, everything is fine.
+With a flaky connection it is pretty common that the browser disconnects, but the actual test execution is still running
+without any problems. Karma does not treat a disconnection as immediate failure and will wait `browserDisconnectTimeout` (ms).
+If the browser reconnects during that time, everything is fine.
 
 
 ## browserDisconnectTolerance
@@ -97,19 +99,20 @@ With a flaky connection it is pretty common that browser disconnects but the act
 
 **Description:** The number of disconnections tolerated.
 
-The `disconnectTolerance` value represents the maximum number of tries a browser will attempt in case of disconnection.
-Usually any disconnection is considered as a failure, but this option allows to define a tolerance level when there is
-a flaky network link between the karma server and the browsers.
+The `disconnectTolerance` value represents the maximum number of tries a browser will attempt in the case of a disconnection.
+Usually any disconnection is considered a failure, but this option allows you to define a tolerance level when there is
+a flaky network link between the Karma server and the browsers.
 
 
 ## browserNoActivityTimeout
 **Type:** Number
 
 **Default:** `10000`
 
-**Description:** How long does Karma wait for a message from a browser before disconnecting it (in ms).
+**Description:** How long will Karma wait for a message from a browser before disconnecting from it (in ms).
 
-If, during the execution, Karma does not receive any message from a browser within `browserNoActivityTimeout` ms, it will disconnect the browser.
+If, during test execution, Karma does not receive any message from a browser within `browserNoActivityTimeout`
+(ms), it will disconnect from the browser.
 
 
 ## browsers
@@ -121,20 +124,20 @@ If, during the execution, Karma does not receive any message from a browser with
 
 **Possible Values:**
 
-  * `Chrome` (comes installed with Karma)
-  * `ChromeCanary` (comes installed with Karma)
-  * `PhantomJS` (comes installed with Karma)
-  * `Firefox` (requires karma-firefox-launcher plugin)
-  * `Opera` (requires karma-opera-launcher plugin)
-  * `Internet Explorer` (requires karma-ie-launcher plugin)
-  * `Safari` (requires karma-safari-launcher plugin)
+  * `Chrome` (launcher comes installed with Karma)
+  * `ChromeCanary` (launcher comes installed with Karma)
+  * `PhantomJS` (launcher comes installed with Karma)
+  * `Firefox` (launcher requires karma-firefox-launcher plugin)
+  * `Opera` (launcher requires karma-opera-launcher plugin)
+  * `Internet Explorer` (launcher requires karma-ie-launcher plugin)
+  * `Safari` (launcher requires karma-safari-launcher plugin)
 
 **Description:** A list of browsers to launch and capture. When Karma starts up, it will also start up each browser
-which is placed within this setting.  Once Karma is shut down, it will shut down these
-browsers as well. You can capture any browser manually just by opening the browser and visiting the URL where
+which is placed within this setting. Once Karma is shut down, it will shut down these
+browsers as well. You can capture any browser manually by opening the browser and visiting the URL where
 the Karma web server is listening (by default it is `http://localhost:9876/`).
 
-See [config/browsers] for more. Additional launchers can be defined through [plugins].
+See [config/browsers] for more information. Additional launchers can be defined through [plugins].
 
 
 ## captureTimeout
@@ -156,7 +159,7 @@ it again and, after three attempts to capture it, Karma will give up.
 **CLI:** All arguments after `--` (only when using `karma run`)
 
 **Description:** When `karma run` is passed additional arguments on the command-line, they
-are passed through to the test adapter as ``karma.config.args` (an array of strings).
+are passed through to the test adapter as `karma.config.args` (an array of strings).
 The `client.args` option allows you to set this value for actions other than `run`.
 
 How this value is used is up to your test adapter - you should check your adapter's
@@ -169,7 +172,7 @@ documentation to see how (and if) it uses this value.
 
 **CLI:** `--colors`, `--no-colors`
 
-**Description:**  Enable or disable colors in the output (reporters and logs).
+**Description:** Enable or disable colors in the output (reporters and logs).
 
 
 ## exclude
@@ -195,7 +198,7 @@ See [config/files] for more information.
 
 **Default:** `[]`
 
-**Description:** List of frameworks you want to use. Typically, you will set this to `['jasmine']`, `['mocha']` or `['qunit']`...
+**Description:** List of test frameworks you want to use. Typically, you will set this to `['jasmine']`, `['mocha']` or `['qunit']`...
 
 Please note just about all frameworks in Karma require an additional plugin/framework library to be installed (via NPM).
 
@@ -233,8 +236,7 @@ Additional information can be found in [plugins].
 
 **Default:** `[{type: 'console'}]`
 
-**Description:** A list of log appenders to be used. See the
-  documentation for [log4js] for more information.
+**Description:** A list of log appenders to be used. See the documentation for [log4js] for more information.
 
 
 ## plugins
@@ -243,9 +245,9 @@ Additional information can be found in [plugins].
 **Default:** `['karma-*']`
 
 **Description:** List of plugins to load. A plugin can be a string (in which case it will be required by Karma) or an inlined plugin - Object.
-By default, Karma loads all siblink modules, that match `karma-*`.
+By default, Karma loads all sibling NPM modules which have a name starting with `karma-*`.
 
-Please note just about all plugins in Karma require an additional library to be installed (via NPM).
+Note: Just about all plugins in Karma require an additional library to be installed (via NPM).
 
 See [plugins] for more information.
 
@@ -257,7 +259,7 @@ See [plugins] for more information.
 
 **CLI:** `--port 9876`
 
-**Description:** The port where the webserver will be listening.
+**Description:** The port where the web server will be listening.
 
 
 ## preprocessors
@@ -269,7 +271,7 @@ See [plugins] for more information.
 
 Preprocessors can be loaded through [plugins].
 
-Please note just about all preprocessors in Karma (other than CoffeeScript and some other defaults)
+Note: Just about all preprocessors in Karma (other than CoffeeScript and some other defaults)
 require an additional library to be installed (via NPM).
 
 Be aware that preprocessors may be transforming the files and file types that are available at run time. For instance,
@@ -284,24 +286,26 @@ Click <a href="preprocessors.html">here</a> for more information.
 ## proxies
 **Type:** Object
 
-**Default:**   `{}`
+**Default:** `{}`
 
 **Description:** A map of path-proxy pairs.
 
 **Example:**
-  ```javascript
-  proxies:  {
-    '/static': 'http://gstatic.com',
-    '/web': 'http://localhost:9000'
-  },
-  ```
+```javascript
+proxies: {
+'/static': 'http://gstatic.com',
+'/web': 'http://localhost:9000'
+},
+```
+
 
 ## proxyValidateSSL
 **Type:** Boolean
 
-**Default:**   `true`
+**Default:** `true`
+
+**Description:** Whether or not Karma or any browsers should raise an error when an inavlid SSL certificate is found.
 
-**Description:** Whether or not karma or any browsers should raise an error when an inavlid SSL certificate is found.
 
 ## reportSlowerThan
 **Type:** Number
@@ -328,7 +332,7 @@ This is disabled by default (since the default value is 0).
 
 Additional reporters, such as `growl`, `junit`, `teamcity` or `coverage` can be loaded through [plugins].
 
-Please note just about all additional reporters in Karma (other than progress) require an additional library to be installed (via NPM).
+Note: Just about all additional reporters in Karma (other than progress) require an additional library to be installed (via NPM).
 
 
 ## singleRun
@@ -358,9 +362,10 @@ between browsers and the testing server).
 
 **Default:** `true`
 
-**Description:** Run the tests inside an iframe or a new window
+**Description:** Run the tests inside an iFrame or a new window
 
-If true, Karma runs the tests inside an iframe. If false, Karma runs the tests in a new window. Some tests may not run in an iFrame and may need a new window to run.
+If true, Karma runs the tests inside an iFrame. If false, Karma runs the tests in a new window. Some tests may not run in an
+iFrame and may need a new window to run.
 
 ## client.captureConsole
 **Type:** Boolean
@@ -376,7 +381,7 @@ If true, Karma runs the tests inside an iframe. If false, Karma runs the tests i
 
 **Description:** The base url, where Karma runs.
 
-All the Karma's urls get prefixed with the `urlRoot`. This is helpful when using proxies, as
+All of Karma's urls get prefixed with the `urlRoot`. This is helpful when using proxies, as
 sometimes you might want to proxy a url that is already taken by Karma.
 
 

docs/config/02-files.md

@@ -2,30 +2,32 @@
 
 
 ## Pattern matching and `basePath`
-- All of the relative patterns will get resolved to `basePath` first.
+- All of the relative patterns will get resolved using the `basePath` first.
 - If the `basePath` is a relative path, it gets resolved to the
-  directory where the configuration file is.
+  directory where the configuration file is located.
 - Eventually, all the patterns will get resolved into files using
   [glob], so you can use [minimatch] expressions like `test/unit/**/*.spec.js`.
 
+
 ## Ordering
-- The order of patterns determines the order of files in which they
-  are included in the browser.
+- The order of patterns determines the order in which files are included in the browser.
 - Multiple files matching a single pattern are sorted alphabetically.
 - Each file is included exactly once. If multiple patterns match the
   same file, it's included as if it only matched the first pattern.
 
+
 ## Included, served, watched
 Each pattern is either a simple string or an object with four properties:
 
 ### `pattern`
+* **Type.** String
+* **No Default.**
 * **Description.** The pattern to use for matching. This property is mandatory.
 
 ### `watched`
 * **Type.** Boolean
 * **Default.** `true`
-* **Description.**  If `autoWatch` is `true` all files that have set `watched` to true will be
-  watched for changes.
+* **Description.**  If `autoWatch` is `true` all files that have set `watched` to true will be watched for changes.
 
 ### `included`
 * **Type.** Boolean
@@ -39,11 +41,13 @@ Each pattern is either a simple string or an object with four properties:
 * **Default.** `true`
 * **Description.** Should the files be served by Karma's webserver?
 
+
 ## Preprocessor transformations
 Depending on preprocessor configuration, be aware that files loaded may be transformed and no longer available in
 their native format. For instance, if html2js preprocessor is enabled, the actual .html files are no longer
 served - but rather available as `window.__html__['my.html']`. Read more about [preprocessors].
 
+
 ## Complete example
 Here is a complete example showing the different options possible:
 ```javascript

docs/config/03-browsers.md

@@ -1,13 +1,14 @@
-Capturing browsers on your own is kinda tedious and time consuming,
-so Karma can do that for you. Just simply add into the configuration file:
+Capturing browsers on your own can be a tedious and time consuming task,
+so Karma can automate this for you. Simply add the browsers you would like to
+capture into the configuration file:
 
 ```javascript
 browsers: ['Chrome']
 ```
 
-Then, Karma will take care of autocapturing these browsers, as well as killing them.
+Then, Karma will take care of auto-capturing these browsers, as well as killing them.
 
-Note: Most of the browser launchers needs to be loaded as [plugins].
+Note: Most of the browser launchers need to be loaded as [plugins].
 
 ## Available browser launchers
 - [Chrome and Chrome Canary] (install karma-chrome-launcher)
@@ -23,7 +24,7 @@ Note: Most of the browser launchers needs to be loaded as [plugins].
 Here's an example of how to add Firefox to your testing suite:
 
 ```bash
-# Install it first with NPM:
+# Install the launcher first with NPM:
 $ npm install karma-firefox-launcher --save-dev
 ```
 
@@ -43,9 +44,12 @@ Of course, you can write [custom plugins] too!
 
 ## Capturing any browser manually
 
-You can also capture browsers by simply opening `http://<hostname>:<port>/`, where `<hostname>` is the IP address or hostname of the machine where Karma server is running and `<port>` is the port where Karma server is listening (by default it's `9876`). With the default settings in place, just point your browser to `http://localhost:9876/`.
+You can also capture browsers by simply opening `http://<hostname>:<port>/`, where `<hostname>` is the IP
+address or hostname of the machine where the Karma server is running and `<port>` is the port where the Karma
+server is listening (by default it's `9876`). With the default settings in place, just point your browser to `http://localhost:9876/`.
 
-This allows you to capture a browser on any device such as a tablet or a phone, that is on the same network as the machine running Karma (or using a local tunnel).
+This allows you to capture a browser on any device, such as a tablet or a phone, that is on the same network
+as the machine running Karma (or using a local tunnel).
 
 
 ## Configured launchers