chore(docs): cleaned up documentation for browser.wait (angular#3967)

The existing documentation was redundant and confusing.

Closes angular#3679

Author: sjelin

lib/selenium-webdriver/webdriver.js

@@ -250,13 +250,16 @@ webdriver.WebDriver.prototype.executeAsyncScript = (script, var_args) => {};
 webdriver.WebDriver.prototype.call = function(fn, opt_scope, var_args) {};
 
 /**
- * Schedules a command to wait for a condition to hold.
+ * Schedules a command to wait for a condition to hold or {@link
+ * webdriver.promise.Promise promise} to be resolved.
  *
- * This function may be used to block the command flow on the resolution
- * of a {@link webdriver.promise.Promise promise}. When given a promise, the
- * command will simply wait for its resolution before completing. A timeout may
- * be provided to fail the command if the promise does not resolve before the
- * timeout expires.
+ * This function blocks WebDriver's control flow, not the javascript runtime.
+ * It will only delay future webdriver commands from being executed (e.g. it
+ * will cause Protractor to wait before sending future commands to the selenium
+ * server), and only when the webdriver control flow is enabled.
+ *
+ * This function returnes a promise, which can be used if you need to block
+ * javascript execution and not just the control flow.
  *
  * See also {@link ExpectedConditions}
  *