Skip to content

Commit 97ca8ab

Browse files
committed
[js] Replace typedefs with record objects for parts of the public API.
This purely a cosmetic change to generate more helpful API docs (typedefs are automatically expanded when used as method parameters, so links to typedef's documentation is lost)
1 parent f2e0f00 commit 97ca8ab

3 files changed

Lines changed: 87 additions & 45 deletions

File tree

‎javascript/node/selenium-webdriver/io/exec.js‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -21,22 +21,37 @@ const childProcess = require('child_process');
2121

2222

2323
/**
24-
* A hash with configuration options for an executed command.
24+
* Options for configuring an executed command.
2525
*
26-
* - `args` - Command line arguments.
27-
* - `env` - Command environment; will inherit from the current process if
28-
* missing.
29-
* - `stdio` - IO configuration for the spawned server process. For more
30-
* information, refer to the documentation of `child_process.spawn`.
31-
*
32-
* @typedef {{
33-
* args: (!Array<string>|undefined),
34-
* env: (!Object<string, string>|undefined),
35-
* stdio: (string|!Array<string|number|!stream.Stream|null|undefined>|
36-
* undefined)
37-
* }}
26+
* @record
3827
*/
39-
var Options;
28+
class Options {
29+
constructor() {
30+
/**
31+
* Command line arguments for the child process, if any.
32+
* @type (!Array<string>|undefined)
33+
*/
34+
this.args;
35+
36+
/**
37+
* Environment variables for the spawned process. If unspecified, the
38+
* child will inherit this process' environment.
39+
*
40+
* @type {(!Object<string, string>|undefined)}
41+
*/
42+
this.env;
43+
44+
/**
45+
* IO conifguration for the spawned server child process. If unspecified,
46+
* the child process' IO output will be ignored.
47+
*
48+
* @type {(string|!Array<string|number|!stream.Stream|null|undefined>|
49+
* undefined)}
50+
* @see <https://nodejs.org/dist/latest-v8.x/docs/api/child_process.html#child_process_options_stdio>
51+
*/
52+
this.stdio;
53+
}
54+
}
4055

4156

4257
/**
@@ -148,6 +163,5 @@ module.exports = function exec(command, opt_options) {
148163
// Exported to improve generated API documentation.
149164

150165
module.exports.Command = Command;
151-
/** @typedef {!Options} */
152166
module.exports.Options = Options;
153167
module.exports.Result = Result;

‎javascript/node/selenium-webdriver/lib/logging.js‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -252,10 +252,6 @@ class Entry {
252252
}
253253

254254

255-
/** @typedef {(string|function(): string)} */
256-
let Loggable;
257-
258-
259255
/**
260256
* An object used to log debugging messages. Loggers use a hierarchical,
261257
* dot-separated naming scheme. For instance, "foo" is considered the parent of
@@ -523,7 +519,7 @@ function getLogger(name) {
523519

524520
/**
525521
* Pads a number to ensure it has a minimum of two digits.
526-
*
522+
*
527523
* @param {number} n the number to be padded.
528524
* @return {string} the padded number.
529525
*/

‎javascript/node/selenium-webdriver/remote/index.js‎

Lines changed: 57 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -500,33 +500,65 @@ class SeleniumServer extends DriverService {
500500

501501

502502
/**
503-
* Options for the Selenium server:
504-
*
505-
* - `loopback` - Whether the server should only be accessed on this host's
506-
* loopback address.
507-
* - `port` - The port to start the server on (must be > 0). If the port is
508-
* provided as a promise, the service will wait for the promise to resolve
509-
* before starting.
510-
* - `args` - The arguments to pass to the service. If a promise is provided,
511-
* the service will wait for it to resolve before starting.
512-
* - `jvmArgs` - The arguments to pass to the JVM. If a promise is provided,
513-
* the service will wait for it to resolve before starting.
514-
* - `env` - The environment variables that should be visible to the server
515-
* process. Defaults to inheriting the current process's environment.
516-
* - `stdio` - IO configuration for the spawned server process. For more
517-
* information, refer to the documentation of `child_process.spawn`.
503+
* A record object describing configuration options for a {@link SeleniumServer}
504+
* instance.
518505
*
519-
* @typedef {{
520-
* loopback: (boolean|undefined),
521-
* port: (number|!IThenable<number>),
522-
* args: !(Array<string>|IThenable<!Array<string>>),
523-
* jvmArgs: (!Array<string>|!IThenable<!Array<string>>|undefined),
524-
* env: (!Object<string, string>|undefined),
525-
* stdio: (string|!Array<string|number|!stream.Stream|null|undefined>|
526-
* undefined)
527-
* }}
506+
* @record
528507
*/
529-
SeleniumServer.Options;
508+
SeleniumServer.Options = class {
509+
constructor() {
510+
/**
511+
* Whether the server should only be accessible on this host's loopback
512+
* address.
513+
*
514+
* @type {(boolean|undefined)}
515+
*/
516+
this.loopback;
517+
518+
/**
519+
* The port to start the server on (must be > 0). If the port is provided as
520+
* a promise, the service will wait for the promise to resolve before
521+
* starting.
522+
*
523+
* @type {(number|!IThenable<number>)}
524+
*/
525+
this.port;
526+
527+
/**
528+
* The arguments to pass to the service. If a promise is provided,
529+
* the service will wait for it to resolve before starting.
530+
*
531+
* @type {!(Array<string>|IThenable<!Array<string>>)}
532+
*/
533+
this.args;
534+
535+
/**
536+
* The arguments to pass to the JVM. If a promise is provided,
537+
* the service will wait for it to resolve before starting.
538+
*
539+
* @type {(!Array<string>|!IThenable<!Array<string>>|undefined)}
540+
*/
541+
this.jvmArgs;
542+
543+
/**
544+
* The environment variables that should be visible to the server
545+
* process. Defaults to inheriting the current process's environment.
546+
*
547+
* @type {(!Object<string, string>|undefined)}
548+
*/
549+
this.env;
550+
551+
/**
552+
* IO configuration for the spawned server process. If unspecified, IO will
553+
* be ignored.
554+
*
555+
* @type {(string|!Array<string|number|!stream.Stream|null|undefined>|
556+
* undefined)}
557+
* @see <https://nodejs.org/dist/latest-v8.x/docs/api/child_process.html#child_process_options_stdio>
558+
*/
559+
this.stdio;
560+
}
561+
};
530562

531563

532564

0 commit comments

Comments
 (0)