chore(docs): Document disabling the control flow

* Added information about `SELENIUM_PROMISE_MANAGER` to `docs/control-flow.md`,
  including pointing to `/spec/ts/` for examples
* Added `docs/async-await.md`, which redirects to
  `exampleTypescript/asyncAwait/README.md`.
* Updated `exampleTypescript/asyncAwait/README.md`, including pointing to
  `/spec/ts/` for more examples.
* Added `docs/typescript.md`, which redirects to `/exampleTypescript/`.
* Added information about `@types/jasminewd2` to `exampleTypescript/README.md`.

Website updates to come in a future change.

Closes #3692.

Author: sjelin

docs/async-await.md

@@ -0,0 +1,4 @@
+`async`/`await`
+===============
+
+Please see [our TypeScript examples which use `async`/`await`](/exampleTypescript/asyncAwait/).

docs/control-flow.md

@@ -6,6 +6,22 @@ which are managed by a [control flow](https://github.com/SeleniumHQ/selenium/wik
 and adapted for [Jasmine](http://jasmine.github.io/2.3/introduction.html).
 A short summary about how Protractor interacts with the control flow is presented below.
 
+Disabling the Control Flow
+--------------------------
+
+In the future, the control flow is being removed (see
+[SeleniumHQ's github issue](https://github.com/SeleniumHQ/selenium/issues/2969)
+for details).  To disable the control flow in your tests, you can use the
+`SELENIUM_PROMISE_MANAGER: false` [config option](/lib/config.ts#L644).
+
+Instead of the control flow, you can synchronize your commands
+with promise chaining or the upcoming ES7 feature `async`/`await`.  See
+[`/spec/ts/`](/spec/ts/) for examples of tests with the control flow disabled.
+
+Because `async`/`await` uses native promises, it will make the Control Flow
+unreliable.  As such, if you're writing a library or plugin which needs to work
+whether or not the Control Flow is enabled, you'll need to handle
+synchronization using promise chaining.
 
 Promises and the Control Flow
 -----------------------------

docs/typescript.md

@@ -0,0 +1,4 @@
+TypeScript
+==========
+
+Please see [our TypeScript examples](/exampleTypescript/).

exampleTypescript/README.md

@@ -65,8 +65,13 @@ export let config: Config = {
 
 ## Ambient typings
 
-Protractor also uses ambient types including jasmine and node. These are brought in via the `tsconfig.json` file, which uses npm module resolution to get types from `node_modules/@types`.
+Protractor also uses ambient types including jasmine, jasminewd2, and node. These are brought in via the `tsconfig.json` file, which uses npm module resolution to get types from `node_modules/@types`.
 
+If you are using the jasmine framework for your tests, make sure to do:
+
+```
+npm install --save-dev @types/jasmine @types/jasminewd2
+```
 
 ## Compiling your code
 

exampleTypescript/asyncAwait/README.md

@@ -2,28 +2,28 @@
 ===============================================
 
 The Web Driver Control Flow is used to synchronize your commands so they reach
-the browser in the correct order (see [control-flow.md](
-../../docs/control-flow.md) for details).  In the future, the control flow is
-being removed, however (see [github issue](
-https://github.com/SeleniumHQ/selenium/issues/2969) for details).  Instead of
-the control flow, you can synchronize your commands with promise chaining or the
-upcomming ES7 feature `async`/`await`.  However, you cannot use a mix of
-`async`/`await` and the control flow: `async`/`await` causes the control flow to
-become unreliable (see [github issue](
-https://github.com/SeleniumHQ/selenium/issues/3037)).  So if you `async`/`await`
-anywhere in a spec, you should use `await` or promise chaining to handle all
-asynchronous activity (e.g. any command interacting with the browser) for the
-rest of that test.
-
-In the near future there will be an option to disable the Web Driver control
-flow entierly (see https://github.com/angular/protractor/issues/3691).  If you
-are using `async`/`await`, it is highly recommended that you disable the Web
-Driver control flow. 
+the browser in the correct order (see
+[/docs/control-flow.md](/docs/control-flow.md) for details).  In the future, the
+control flow is being removed (see [SeleniumHQ's github issue](
+https://github.com/SeleniumHQ/selenium/issues/2969) for details). Instead of the
+control flow, you can synchronize your commands with promise chaining or the
+upcoming ES7 feature `async`/`await`.
 
+However, you cannot use a mix of `async`/`await` and the control flow:
+`async`/`await` causes the control flow to become unreliable (see
+[github issue]( https://github.com/SeleniumHQ/selenium/issues/3037)).  So if you
+`async`/`await` anywhere in a spec, you should use the
+`SELENIUM_PROMISE_MANAGER: false` [config option](/lib/config.ts#L644).
 
 Compiling `async`/`await` syntax
 ================================
 
 `async`/`await` syntax is currently accessible via typescript if you compile
-using `tsc -t ES2015 <files>`.  You can also compile it using [regenerator](
+using `--target ES2015` or above.  You can also compile it using [regenerator](
   https://github.com/facebook/regenerator).
+
+
+More Examples
+=============
+
+More examples can be found under [`/spec/ts/`](/../../spec/ts).

exampleTypescript/asyncAwait/conf.ts

@@ -11,5 +11,6 @@ export let config: Config  = {
     browserName: 'chrome'
   },
   specs: [ 'spec.js' ],
-  seleniumAddress: 'http://localhost:4444/wd/hub'
+  seleniumAddress: 'http://localhost:4444/wd/hub',
+  SELENIUM_PROMISE_MANAGER: false
 };

exampleTypescript/package.json

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@types/jasmine": "^2.5.38",
+    "@types/jasminewd2": "^2.0.0",
     "jasmine": "^2.4.1",
     "protractor": "file:../",
     "typescript": "~2.0.0"

exampleTypescript/tsconfig.json

@@ -6,8 +6,7 @@
     "sourceMap": false,
     "declaration": false,
     "noImplicitAny": false,
-    "outDir": "tmp",
-    "types": ["node", "jasmine"]
+    "outDir": "tmp"
   },
   "exclude": [
     "node_modules",