Clean up some documentation and remove a few circular dependencies that

complicate static analysis.

Author: jleyba

javascript/node/selenium-webdriver/_base.js

@@ -17,11 +17,11 @@
  * @fileoverview The base module responsible for bootstrapping the Closure
  * library and providing a means of loading Closure-based modules.
  *
- * Each script loaded by this module will be granted access to this module's
+ * <p>Each script loaded by this module will be granted access to this module's
  * {@code require} function; all required non-native modules must be specified
  * relative to <em>this</em> module.
  *
- * This module will load all scripts from the "lib" subdirectory, unless the
+ * <p>This module will load all scripts from the "lib" subdirectory, unless the
  * SELENIUM_DEV_MODE environment variable has been set to 1, in which case all
  * scripts will be loaded from the Selenium client containing this script.
  */
@@ -44,18 +44,46 @@ var devMode = (function() {
 })();
 
 
+/** @return {boolean} Whether this script was loaded in dev mode. */
+function isDevMode() {
+  return devMode;
+}
+
+
 /**
  * @type {string} Path to Closure's base file, relative to this module.
  * @const
  */
-var CLOSURE_BASE_FILE_PATH = computeClosureBasePath();
+var CLOSURE_BASE_FILE_PATH = (function() {
+  var relativePath = isDevMode() ?
+      '../../../third_party/closure/goog/base.js' :
+      './lib/goog/base.js';
+  return path.join(__dirname, relativePath);
+})();
 
 
 /**
  * @type {string} Path to Closure's base file, relative to this module.
  * @const
  */
-var DEPS_FILE_PATH = computeDepsPath();
+var DEPS_FILE_PATH = (function() {
+  var relativePath = isDevMode() ?
+      '../../../javascript/deps.js' :
+      './lib/deps.js';
+  return path.join(__dirname, relativePath);
+})();
+
+
+
+/**
+ * Synchronously loads a script into the protected Closure context.
+ * @param {string} src Path to the file to load.
+ */
+function loadScript(src) {
+  src = path.normalize(src);
+  var contents = fs.readFileSync(src, 'utf8');
+  vm.runInContext(contents, closure, src);
+}
 
 
 /**
@@ -78,18 +106,20 @@ var closure = vm.createContext({
     loadScript(src);
     return true;
   },
-  CLOSURE_NO_DEPS: !isDevMode()
+  CLOSURE_NO_DEPS: !isDevMode(),
+  goog: {}
 });
 closure.window = closure;
 
+
 loadScript(CLOSURE_BASE_FILE_PATH);
 loadScript(DEPS_FILE_PATH);
 
 
 /**
  * Loads a symbol by name from the protected Closure context.
  * @param {string} symbol The symbol to load.
- * @return {*} The loaded symbol.
+ * @return {?} The loaded symbol, or {@code null} if not found.
  * @throws {Error} If the symbol has not been defined.
  */
 function closureRequire(symbol) {
@@ -98,42 +128,6 @@ function closureRequire(symbol) {
 }
 
 
-/** @return {string} Path to the closure library's base script. */
-function computeClosureBasePath() {
-  var relativePath = isDevMode() ?
-      '../../../third_party/closure/goog/base.js' :
-      './lib/goog/base.js';
-  return path.join(__dirname, relativePath);
-}
-
-
-/** @return {string} Path to the deps file used to locate closure resources. */
-function computeDepsPath() {
-  var relativePath = isDevMode() ?
-      '../../../javascript/deps.js' :
-      './lib/deps.js';
-  return path.join(__dirname, relativePath);
-}
-
-
-/** @return {boolean} Whether this script was loaded in dev mode. */
-function isDevMode() {
-  return devMode;
-}
-exports.isDevMode = isDevMode;
-
-
-/**
- * Synchronously loads a script into the protected Closure context.
- * @param {string} src Path to the file to load.
- */
-function loadScript(src) {
-  src = path.normalize(src);
-  var contents = fs.readFileSync(src, 'utf8');
-  vm.runInContext(contents, closure, src);
-}
-
-
 // PUBLIC API
 
 

javascript/node/selenium-webdriver/builder.js

@@ -50,6 +50,7 @@ function createNativeDriver(capabilities) {
 
 
 /**
+ * Creates new {@link webdriver.WebDriver WebDriver} instances.
  * @constructor
  * @extends {webdriver.AbstractBuilder}
  */
@@ -63,7 +64,7 @@ goog.inherits(Builder, AbstractBuilder);
  * Sets the proxy configuration to use for WebDriver clients created by this
  * builder. Any calls to {@link #withCapabilities} after this function will
  * overwrite these settings.
- * @param {!ProxyConfig} config The configuration to use.
+ * @param {!proxy.ProxyConfig} config The configuration to use.
  * @return {!Builder} A self reference.
  */
 Builder.prototype.setProxy = function(config) {

javascript/node/selenium-webdriver/chrome.js

@@ -45,6 +45,7 @@ var CHROMEDRIVER_EXE =
  * @constructor
  */
 var ServiceBuilder = function(opt_exe) {
+  /** @private {string} */
   this.exe_ = opt_exe || io.findInPath(CHROMEDRIVER_EXE, true);
   if (!this.exe_) {
     throw Error(
@@ -58,6 +59,7 @@ var ServiceBuilder = function(opt_exe) {
     throw Error('File does not exist: ' + this.exe_);
   }
 
+  /** @private {!Array.<string>} */
   this.args_ = [];
   this.stdio_ = 'ignore';
 };

javascript/node/selenium-webdriver/error.js

@@ -0,0 +1,25 @@
+// Copyright 2014 Selenium committers
+// Copyright 2014 Software Freedom Conservancy
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+//     You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+var base = require('./_base');
+
+
+/** @type {function(new: bot.Error)} */
+exports.Error = base.require('bot.Error');
+
+/** @type {bot.ErrorCode.} */
+exports.ErrorCode = base.require('bot.ErrorCode');

javascript/node/selenium-webdriver/executors.js

@@ -17,9 +17,9 @@
  * {@link webdriver.CommandExecutor} implementations.
  */
 
-var webdriver = require('./index'),
-    HttpClient = require('./http').HttpClient,
-    HttpExecutor = require('./http').Executor;
+var HttpClient = require('./http').HttpClient,
+    HttpExecutor = require('./http').Executor,
+    promise = require('./_base').require('webdriver.promise');
 
 
 
@@ -52,7 +52,7 @@ var DeferredExecutor = function(delegate) {
  * @returns {!webdriver.CommandExecutor} The new command executor.
  */
 exports.createExecutor = function(url) {
-  return new DeferredExecutor(webdriver.promise.when(url, function(url) {
+  return new DeferredExecutor(promise.when(url, function(url) {
     var client = new HttpClient(url);
     return new HttpExecutor(client);
   }));

javascript/node/selenium-webdriver/http/index.js

@@ -25,7 +25,8 @@ var base = require('../_base'),
 
 
 /**
- * HTTP client for use with NodeJS.
+ * A {@link webdriver.http.Client} implementation using Node's built-in http
+ * module.
  * @param {string} serverUrl URL for the WebDriver server to send commands to.
  * @constructor
  * @implements {webdriver.http.Client}
@@ -138,9 +139,13 @@ var sendRequest = function(options, callback, opt_data) {
 
 // PUBLIC API
 
-
+/** @type {webdriver.http.Executor.} */
 exports.Executor = base.require('webdriver.http.Executor');
+
+/** @type {webdriver.http.Request.} */
 exports.Request = base.require('webdriver.http.Request');
+
+/** @type {webdriver.http.Response.} */
 exports.Response = base.require('webdriver.http.Response');
+
 exports.HttpClient = HttpClient;
-exports.util = require('./util');

javascript/node/selenium-webdriver/index.js

@@ -19,42 +19,106 @@
  */
 
 var base = require('./_base');
+var builder = require('./builder');
+var error = require('./error');
 
+
+// NOTE: the remainder of this file is nasty and verbose, but the annotations
+// are necessary to guide the Closure Compiler's type analysis. Without them,
+// we would not be able to extract any meaningful API documentation.
+
+
+/** @type {function(new: webdriver.ActionSequence)} */
 exports.ActionSequence = base.require('webdriver.ActionSequence');
-exports.Builder = require('./builder').Builder;
-exports.Button = base.require('webdriver.Button');
-exports.By = base.require('webdriver.Locator.Strategy');
+
+
+/** @type {function(new: builder.Builder)} */
+exports.Builder = builder.Builder;
+
+
+/** @type {function(new: webdriver.Capabilities)} */
 exports.Capabilities = base.require('webdriver.Capabilities');
+
+
+/** @type {function(new: webdriver.Command)} */
 exports.Command = base.require('webdriver.Command');
+
+
+/** @type {function(new: webdriver.EventEmitter)} */
 exports.EventEmitter = base.require('webdriver.EventEmitter');
+
+
+/** @type {function(new: webdriver.Session)} */
 exports.Session = base.require('webdriver.Session');
+
+
+/** @type {function(new: webdriver.WebDriver)} */
 exports.WebDriver = base.require('webdriver.WebDriver');
+
+
+/** @type {function(new: webdriver.WebElement)} */
 exports.WebElement = base.require('webdriver.WebElement');
 
-var closureModules = {
-  Browser: base.require('webdriver.Browser'),
-  Capability: base.require('webdriver.Capability'),
-  CommandName: base.require('webdriver.CommandName'),
-  Key: base.require('webdriver.Key'),
-  command: {
-    Command: base.require('webdriver.Command'),
-    CommandName: base.require('webdriver.CommandName')
-  },
-  error: {
-    Error: base.require('bot.Error'),
-    ErrorCode: base.require('bot.ErrorCode')
-  },
-  events: {
-    EventEmitter: base.require('webdriver.EventEmitter')
-  },
-  logging: base.exportPublicApi('webdriver.logging'),
-  promise: base.exportPublicApi('webdriver.promise'),
-  stacktrace: base.exportPublicApi('webdriver.stacktrace')
-};
-
-
-Object.keys(closureModules).forEach(function(key) {
-  exports.__defineGetter__(key, function() {
-    return closureModules[key];
-  });
-});
+
+// Export the remainder of our API through getters to keep things cleaner
+// when this module is used in a REPL environment.
+
+
+/** @type {webdriver.Browser.} */
+(exports.__defineGetter__('Browser', function() {
+  return base.require('webdriver.Browser');
+}));
+
+
+/** @type {webdriver.Button.} */
+(exports.__defineGetter__('Button', function() {
+  return base.require('webdriver.Button');
+}));
+
+
+/** @type {webdriver.Locator.Strategy.} */
+(exports.__defineGetter__('By', function() {
+  return base.require('webdriver.Locator.Strategy');
+}));
+
+
+/** @type {webdriver.Capability.} */
+(exports.__defineGetter__('Capability', function() {
+  return base.require('webdriver.Capability');
+}));
+
+
+/** @type {webdriver.CommandName.} */
+(exports.__defineGetter__('CommandName', function() {
+  return base.require('webdriver.CommandName');
+}));
+
+
+/** @type {webdriver.Key.} */
+(exports.__defineGetter__('Key', function() {
+  return base.require('webdriver.Key');
+}));
+
+
+/** @type {error.} */
+(exports.__defineGetter__('error', function() {
+  return error;
+}));
+
+
+/** @type {error.} */
+(exports.__defineGetter__('error', function() {
+  return error;
+}));
+
+
+/** @type {webdriver.promise.} */
+(exports.__defineGetter__('promise', function() {
+  return base.exportPublicApi('webdriver.promise');
+}));
+
+
+/** @type {webdriver.stacktrace.} */
+(exports.__defineGetter__('stacktrace', function() {
+  return base.exportPublicApi('webdriver.stacktrace');
+}));

javascript/node/selenium-webdriver/io/index.js

@@ -24,7 +24,7 @@ var PATH_SEPARATOR = process.platform === 'win32' ? ';' : ':';
 
 
 /**
- * Searches the PATH environment variable for the given file.
+ * Searches the {@code PATH} environment variable for the given file.
  * @param {string} file The file to locate on the PATH.
  * @param {boolean=} opt_checkCwd Whether to always start with the search with
  *     the current working directory, regardless of whether it is explicitly

javascript/node/selenium-webdriver/net/portprober.js

@@ -144,6 +144,8 @@ function findWindowsPortRange() {
 /**
  * Tests if a port is free.
  * @param {number} port The port to test.
+ * @param {string=} opt_host The bound host to test the {@code port} against.
+ *     Defaults to {@code INADDR_ANY}.
  * @return {!webdriver.promise.Promise.<boolean>} A promise that will resolve
  *     with whether the port is free.
  */
@@ -171,6 +173,8 @@ function isFree(port, opt_host) {
 
 
 /**
+ * @param {string=} opt_host The bound host to test the {@code port} against.
+ *     Defaults to {@code INADDR_ANY}.
  * @return {!webdriver.promise.Promise.<number>} A promise that will resolve
  *     to a free port. If a port cannot be found, the promise will be
  *     rejected.