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

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() {