chore(examples): update async/await example with better info

Author: sjelin

exampleTypescript/asyncAwait/README.md

@@ -1,8 +1,25 @@
-`async`/`await` in Protractor
-=============================
-
-`async`/`await` is a feature that may or may not be added to javascript in
-the future.  It is currently accessible via typescript if you compile using
-`tsc -t ES2015 <files>`.  Protractor supports returning a promise at the end of
-an `it()` block, so it indirectly supports `async`/`await` (so long as your
-programming environment supports it).
+`async`/`await` and the Web Driver Control Flow
+===============================================
+
+An `async` function returns a promise.  Protractor supports returning a promise
+from an `it()` block, so this isn't necessarily a problem.  The issue is that
+the Web Driver control flow only works with the promise implementation given by
+the `selenium-webdriver` module.  So if you use `async`/`await`, you can no
+longer rely on  Web Driver to synchronize your commands (see [github issue](
+https://github.com/SeleniumHQ/selenium/issues/3037)) for details.  In other
+words, 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. 
+
+
+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](
+  https://github.com/facebook/regenerator).

exampleTypescript/asyncAwait/spec.ts

@@ -1,5 +1,4 @@
-// Same process for importing and compiling at ../spec.ts, except you need to
-// pass the `-t ES2015` flag to `tsc`.
+// See README.md for important details.
 import {browser, element, by, By, $, $$, ExpectedConditions} from 'protractor';
 
 describe('async function', function() {