chore(docgen): fix docgen for 5.1 (#4048)

Also added the ability to run `generate-docs.sh` against a custom
branch/tag/commit by doing `./scripts/generate-docs.sh branch_name`.  Still
defaults to the version from package.json though.

Also updated release.md to tell people to check that doc generation/the website
is working BEFORE doing a release.  Needing a change in the codebase is more
likely now that we're compiling down to es5 only this one time, and ideally
any changes to the codebase would happen before release.

Also including a minor change in the codebase where we wrap a promise from
blocking proxy in a webdriver promise.  This probably should have been done the
whole time, but is unlikely to matter either way at runtime, since blocking
proxy wouldn't be returning a webdriver promise regardless.  Mostly did I did
this to fix typechecking.

Author: sjelin

Diff for: lib/browser.ts

@@ -56,13 +56,14 @@ export interface AbstractExtendedWebDriver extends ExtendedWebDriver {}
  */
 function ptorMixin(to: any, from: any, fnName: string, setupFn?: Function) {
   to[fnName] = function() {
-    for (let i = 0; i < arguments.length; i++) {
-      if (arguments[i] instanceof ElementFinder) {
-        arguments[i] = arguments[i].getWebElement();
+    const args = arguments;
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] instanceof ElementFinder) {
+        args[i] = args[i].getWebElement();
       }
     }
     const run = () => {
-      return from[fnName].apply(from, arguments);
+      return from[fnName].apply(from, args);
     };
     if (setupFn) {
       const setupResult = setupFn();
@@ -201,7 +202,9 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
         return wdpromise.when(value).then((value: string) => {
           this.internalRootEl = value;
           if (this.bpClient) {
-            return this.bpClient.setWaitParams(value).then(() => this.internalRootEl);
+            const bpCommandPromise = this.bpClient.setWaitParams(value);
+            // Convert to webdriver promise as best as possible
+            return wdpromise.when(bpCommandPromise as any).then(() => this.internalRootEl);
           }
           return this.internalRootEl;
         });
@@ -420,9 +423,9 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
         return wdpromise.when(enabled).then((enabled: boolean) => {
           if (this.bpClient) {
             logger.debug('Setting waitForAngular' + !enabled);
-            return this.bpClient.setWaitEnabled(enabled).then(() => {
-              return enabled;
-            });
+            const bpCommandPromise = this.bpClient.setWaitEnabled(enabled);
+            // Convert to webdriver promise as best as possible
+            return wdpromise.when(bpCommandPromise as any).then(() => enabled);
           }
         });
       }, `Set proxy synchronization enabled to ${enabled}`);
@@ -454,7 +457,6 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
    * var fork = browser.forkNewDriverInstance();
    * fork.get('page1'); // 'page1' gotten by forked browser
    *
-   * @example
    * // Running with control flow disabled
    * var forked = await browser.forkNewDriverInstance().ready;
    * await forked.get('page1'); // 'page1' gotten by forked browser
@@ -493,13 +495,11 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
    * browser.restart();
    * browser.get('page2'); // 'page2' gotten by restarted browser
    *
-   * @example
    * // Running against global browser, with control flow disabled
    * await browser.get('page1');
    * await browser.restart();
    * await browser.get('page2'); // 'page2' gotten by restarted browser
    *
-   * @example
    * // Running against forked browsers, with the control flow enabled
    * // In this case, you may prefer `restartSync` (documented below)
    * var forked = browser.forkNewDriverInstance();
@@ -508,14 +508,12 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
    *   fork.get('page2'); // 'page2' gotten by restarted fork
    * });
    *
-   * @example
    * // Running against forked browsers, with the control flow disabled
    * var forked = await browser.forkNewDriverInstance().ready;
    * await fork.get('page1');
    * fork = await fork.restart();
    * await fork.get('page2'); // 'page2' gotten by restarted fork
    *
-   * @example
    * // Unexpected behavior can occur if you save references to the global `browser`
    * var savedBrowser = browser;
    * browser.get('foo').then(function() {
@@ -540,7 +538,6 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
    * browser.restartSync();
    * browser.get('page2'); // 'page2' gotten by restarted browser
    *
-   * @example
    * // Running against forked browsers
    * var forked = browser.forkNewDriverInstance();
    * fork.get('page1');

Diff for: release.md

@@ -17,6 +17,11 @@ Say the previous release was 0.0.J, the current release is 0.0.K, and the next r
 
  - Make sure .gitignore and .npmignore are updated with any new files that need to be ignored.
 
+ - Make sure that the website and doc generation still work.  Doing so now, before you update the package.json or CHANGELOG.md, will save you a big headache.
+   - Run `./scripts/generate-docs.sh HEAD` to generate the docs against the current commit.
+   - We have to compile down to es5 to get dgeni to work. `generate-docs.sh` can handle some of this but you may have to make minor changes to the codebase/build infrastructure.
+   - Run the unit and e2e tests for the website.
+
  - Update package.json with a version bump. If the changes are only bug fixes, increment the patch (e.g. 0.0.5 -> 0.0.6), otherwise increment the minor version.
 
  - Update CHANGELOG.md.
@@ -41,9 +46,7 @@ Say the previous release was 0.0.J, the current release is 0.0.K, and the next r
 
  - NPM publish
 
- - Update the website. `./scripts/generate-docs.sh`. Run unit and e2e tests. Then switch to the
-   `gh-pages` branch, edit the commit message with `git commit --amend`,
-   and push the new website.
+ - Update the website. Run `./scripts/generate-docs.sh`, then switch to the `gh-pages` branch, edit the commit message with `git commit --amend`, and push the new website.
 
  - Run e2e test against the published website.
 

Diff for: scripts/generate-docs.sh

@@ -1,6 +1,12 @@
 #!/bin/sh
 cd "$( dirname "${BASH_SOURCE[0]}" )/.."
 
+# Check number of parameters
+if [ "$#" -gt 1 ]; then
+  echo "Usage: ./scripts/generate-docs.sh [commit_ref]"
+  exit 1
+fi
+
 # Check that directory is clean
 if [ $(git status --porcelain | wc -l) != "0" ]; then
   echo -e "\033[0;31m" 1>&2 # Red
@@ -12,14 +18,25 @@ if [ $(git status --porcelain | wc -l) != "0" ]; then
   exit 1
 fi
 
-echo "Switching to last release..."
-VERSION=$(node scripts/get-version.js)
+# If a commit ref is passed as a command line option, use that.
+# Otherwise, default to the tag corresponding to the version in package.json.
+if [ "$#" -eq 0 ]; then
+  VERSION=$(node scripts/get-version.js)
+else
+  VERSION=$1
+fi
 EXEC_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+echo "Switching to ${VERSION}..."
 git checkout "${VERSION}"
 if [ $? -ne 0 ]; then
   echo -e "\033[0;31m" 1>&2 # Red
-  echo "The package.json file indicates that the current version is" 1>&2
-  echo "\"${VERSION}\", but there is no corresponding git tag." 1>&2
+  if [ "$#" -eq 0 ]; then
+    echo "The package.json file indicates that the current version is" 1>&2
+    echo "\"${VERSION}\", but there is no corresponding git tag." 1>&2
+  else
+    echo "Cannot checkout \"${VERSION}\"." 1>&2
+  fi
   echo -e "\033[0m" 1>&2 # Normal Color
   git checkout "${EXEC_BRANCH}"
   exit 1
@@ -61,6 +78,7 @@ if [ $? -ne 0 ]; then
   echo -e "\033[0;31m" 1>&2 # Red
   echo "Couldn't compile for es5."
   echo -e "\033[0m" 1>&2 # Normal Color
+  npm remove @types/es6-promise
   git checkout "${EXEC_BRANCH}"
   exit 1
 fi

Diff for: tsconfig.json

@@ -7,13 +7,7 @@
     "declaration": true,
     "removeComments": false,
     "noImplicitAny": true,
-    "outDir": "built/",
-    "types": [
-      "jasmine", "jasminewd2", "node",
-      "chalk", "glob", "minimatch",
-      "minimist", "optimist", "q",
-      "selenium-webdriver"
-    ]
+    "outDir": "built/"
   },
   "exclude": [
     "built",