Docs: onPrepare should return a promise

docs/referenceConf.js

@@ -197,6 +197,10 @@ exports.config = {
   // capability.
   // You can specify a file containing code to run by setting onPrepare to
   // the filename string.
+  // If the preparation involves any asynchronous calls (e.g. interacting with
+  // the browser), it should return a promise. Otherwise Protractor will be
+  // unable to guarantee order of execution and may start the tests before
+  // preparation finishes.
   onPrepare: function() {
     // At this point, global variable 'protractor' object will be set up, and
     // globals from the test framework will be available. For example, if you
@@ -206,7 +210,7 @@ exports.config = {
     //
     // If you need access back to the current configuration object,
     // use a pattern like the following:
-    //     browser.getProcessedConfig().then(function(config) {
+    //     return browser.getProcessedConfig().then(function(config) {
     //       // config.capabilities is the CURRENT capability being run, if
     //       // you are using multiCapabilities.
     //       console.log('Executing capability', config.capabilities);

docs/system-setup.md

@@ -8,4 +8,8 @@ There are a couple of things to watch out for!
 
 **If your page uses `$timeout` for polling** Protractor will not be able to tell when your page is ready. Consider using `$interval` instead of `$timeout`.
 
-If you need to do global preparation for your tests (for example, logging in), you can put this into the config in the `onPrepare` property. This property can be either a function or a filename. If a filename, Protractor will load that file with Node.js and run its contents. See the [login tests](https://github.com/angular/protractor/blob/master/spec/withLoginConf.js) for an example.
+**If you need to do global preparation for your tests* (for example, logging in), you can put this into the config in the `onPrepare` property. This property can be either a function or a filename. If a filename, Protractor will load that file with Node.js and run its contents.
+
+If the preparation involves any asynchronous calls (e.g. interacting with the browser), it should return a promise. Otherwise Protractor will be unable to guarantee order of execution and may start the tests before preparation finishes. 
+
+See the [login tests](https://github.com/angular/protractor/blob/master/spec/withLoginConf.js) for an example.