Skip to content

Commit 66d5613

Browse files
committed
[js] More changes to improve API docs
1 parent 9bfdbb3 commit 66d5613

File tree

5 files changed

+173
-33
lines changed

5 files changed

+173
-33
lines changed

javascript/node/externs/adm-zip.js

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
// Licensed to the Software Freedom Conservancy (SFC) under one
2+
// or more contributor license agreements. See the NOTICE file
3+
// distributed with this work for additional information
4+
// regarding copyright ownership. The SFC licenses this file
5+
// to you under the Apache License, Version 2.0 (the
6+
// "License"); you may not use this file except in compliance
7+
// with the License. You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
18+
/**
19+
* @fileoverview Extern definitions for https://www.npmjs.com/package/adm-zip
20+
*/
21+
22+
/** @const */
23+
var adm = {};
24+
25+
26+
/** @constructor */
27+
function EntryHeader() {}
28+
29+
/** @type {number} */
30+
EntryHeader.prototype.method;
31+
32+
33+
/**
34+
* @constructor
35+
*/
36+
function ZipEntry() {}
37+
38+
/**
39+
* @type {!EntryHeader}
40+
*/
41+
ZipEntry.prototype.header;
42+
43+
44+
/**
45+
* @param {string=} path
46+
* @constructor
47+
*/
48+
adm.AdmZip = function(path) {};
49+
50+
/**
51+
* @param {string} localPath
52+
* @param {string=} zipPath
53+
* @return {void}
54+
*/
55+
adm.AdmZip.prototype.addLocalFolder = function(localPath, zipPath) {};
56+
57+
/**
58+
* @param {string} localPath
59+
* @param {string=} zipPath
60+
* @return {void}
61+
*/
62+
adm.AdmZip.prototype.addLocalFile = function(localPath, zipPath) {};
63+
64+
/**
65+
* @param {string} path
66+
* @param {boolean=} overwrite
67+
* @return {void}
68+
*/
69+
adm.AdmZip.prototype.extractAllTo = function(path, overwrite) {};
70+
71+
/**
72+
* @param {string} path
73+
* @return {ZipEntry}
74+
*/
75+
adm.AdmZip.prototype.getEntry = function(path) {};
76+
77+
/**
78+
* @return {!Array<!ZipEntry>}
79+
*/
80+
adm.AdmZip.prototype.getEntries = function() {};
81+
82+
/**
83+
* @param {string} entry
84+
* @param {function(string)} callback
85+
* @param {string=} encoding
86+
* @return {void}
87+
*/
88+
adm.AdmZip.prototype.readAsTextAsync = function(entry, callback, encoding) {};
89+
90+
/**
91+
* @param {string} path
92+
* @return {void}
93+
*/
94+
adm.AdmZip.prototype.writeZip = function(path) {};
95+
96+
/** @return {!Buffer} */
97+
adm.AdmZip.prototype.toBuffer = function() {};
98+
99+
100+
module.exports = adm.AdmZip;

javascript/node/gendocs.js

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,7 @@ function buildConfig(modules) {
196196
],
197197
externs: [path.join(externs, 'global.js')],
198198
externModules: [
199+
path.join(externs, 'adm-zip.js'),
199200
path.join(externs, 'mocha.js'),
200201
path.join(externs, 'rimraf.js'),
201202
path.join(externs, 'tmp.js'),
@@ -204,7 +205,8 @@ function buildConfig(modules) {
204205
],
205206
sourceUrlTemplate:
206207
'https://github.com/SeleniumHQ/selenium/tree/master/'
207-
+ 'javascript/node/selenium-webdriver/${path}#L${line}'
208+
+ 'javascript/node/selenium-webdriver/%path%#L%line%',
209+
strict: true
208210
}
209211
}
210212

javascript/node/selenium-webdriver/firefox/extension.js

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,10 @@ function install(extension, dir) {
7878
*/
7979
var AddonDetails;
8080

81+
/** @typedef {{$: !Object<string, string>}} */
82+
var RdfRoot;
83+
84+
8185

8286
/**
8387
* Extracts the details needed to install an add-on.
@@ -119,7 +123,7 @@ function getDetails(addonPath) {
119123
throw new AddonFormatError('Malformed manifest for add-on ' + addonPath);
120124
}
121125

122-
var namespaces = doc[keys[0]].$;
126+
var namespaces = /** @type {!RdfRoot} */(doc[keys[0]]).$;
123127
var id = '';
124128
Object.keys(namespaces).some(function(ns) {
125129
if (namespaces[ns] !== url) {

javascript/node/selenium-webdriver/firefox/profile.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
'use strict';
2424

2525
const AdmZip = require('adm-zip'),
26-
AdmConstants = require('adm-zip/util/constants'),
2726
fs = require('fs'),
2827
path = require('path'),
2928
vm = require('vm');
@@ -385,7 +384,8 @@ class Profile {
385384
return this.writeToDisk(true).then(function(dir) {
386385
var zip = new AdmZip();
387386
zip.addLocalFolder(dir, '');
388-
zip.getEntries()[0].header.method = AdmConstants.STORED;
387+
// Stored compression, see https://en.wikipedia.org/wiki/Zip_(file_format)
388+
zip.getEntries()[0].header.method = 0;
389389
return io.tmpFile().then(function(file) {
390390
zip.writeZip(file); // Sync! Why oh why :-(
391391
return promise.checkedNodeCall(fs.readFile, file);

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

Lines changed: 63 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818
'use strict';
1919

2020
const AdmZip = require('adm-zip'),
21-
AdmConstants = require('adm-zip/util/constants'),
2221
fs = require('fs'),
2322
path = require('path'),
2423
url = require('url'),
@@ -36,36 +35,69 @@ const httpUtil = require('../http/util'),
3635

3736

3837
/**
39-
* Configuration options for a DriverService instance.
38+
* A record object that defines the configuration options for a DriverService
39+
* instance.
4040
*
41-
* - `loopback` - Whether the service should only be accessed on this host's
42-
* loopback address.
43-
* - `hostname` - The host name to access the server on. If this option is
44-
* specified, the `loopback` option will be ignored.
45-
* - `port` - The port to start the server on (must be > 0). If the port is
46-
* provided as a promise, the service will wait for the promise to resolve
47-
* before starting.
48-
* - `args` - The arguments to pass to the service. If a promise is provided,
49-
* the service will wait for it to resolve before starting.
50-
* - `path` - The base path on the server for the WebDriver wire protocol
51-
* (e.g. '/wd/hub'). Defaults to '/'.
52-
* - `env` - The environment variables that should be visible to the server
53-
* process. Defaults to inheriting the current process's environment.
54-
* - `stdio` - IO configuration for the spawned server process. For more
55-
* information, refer to the documentation of `child_process.spawn`.
41+
* @record
42+
*/
43+
function ServiceOptions() {}
44+
45+
/**
46+
* Whether the service should only be accessed on this host's loopback address.
5647
*
57-
* @typedef {{
58-
* loopback: (boolean|undefined),
59-
* hostname: (string|undefined),
60-
* port: (number|!promise.Promise<number>),
61-
* args: !(Array<string>|promise.Promise<!Array<string>>),
62-
* path: (string|undefined|null),
63-
* env: (Object<string, string>|undefined),
64-
* stdio: (string|!Array<string|number|!stream.Stream|null|undefined>|
65-
* undefined)
66-
* }}
48+
* @type {(boolean|undefined)}
49+
*/
50+
ServiceOptions.prototype.loopback;
51+
52+
/**
53+
* The host name to access the server on. If this option is specified, the
54+
* {@link #loopback} option will be ignored.
55+
*
56+
* @type {(string|undefined)}
57+
*/
58+
ServiceOptions.prototype.hostname;
59+
60+
/**
61+
* The port to start the server on (must be > 0). If the port is provided as a
62+
* promise, the service will wait for the promise to resolve before starting.
63+
*
64+
* @type {(number|!promise.Promise<number>)}
65+
*/
66+
ServiceOptions.prototype.port;
67+
68+
/**
69+
* The arguments to pass to the service. If a promise is provided, the service
70+
* will wait for it to resolve before starting.
71+
*
72+
* @type {!(Array<string>|promise.Promise<!Array<string>>)}
73+
*/
74+
ServiceOptions.prototype.args;
75+
76+
/**
77+
* The base path on the server for the WebDriver wire protocol (e.g. '/wd/hub').
78+
* Defaults to '/'.
79+
*
80+
* @type {(string|undefined|null)}
81+
*/
82+
ServiceOptions.prototype.path;
83+
84+
/**
85+
* The environment variables that should be visible to the server process.
86+
* Defaults to inheriting the current process's environment.
87+
*
88+
* @type {(Object<string, string>|undefined)}
89+
*/
90+
ServiceOptions.prototype.env;
91+
92+
/**
93+
* IO configuration for the spawned server process. For more information, refer
94+
* to the documentation of `child_process.spawn`.
95+
*
96+
* @type {(string|!Array<string|number|!stream.Stream|null|undefined>|
97+
* undefined)}
98+
* @see https://nodejs.org/dist/latest-v4.x/docs/api/child_process.html#child_process_options_stdio
6799
*/
68-
var ServiceOptions;
100+
ServiceOptions.prototype.stdio;
69101

70102

71103
/**
@@ -358,7 +390,8 @@ class FileDetector extends input.FileDetector {
358390

359391
var zip = new AdmZip();
360392
zip.addLocalFile(filePath);
361-
zip.getEntries()[0].header.method = AdmConstants.STORED;
393+
// Stored compression, see https://en.wikipedia.org/wiki/Zip_(file_format)
394+
zip.getEntries()[0].header.method = 0;
362395

363396
var command = new cmd.Command(cmd.Name.UPLOAD_FILE)
364397
.setParameter('file', zip.toBuffer().toString('base64'));
@@ -379,3 +412,4 @@ class FileDetector extends input.FileDetector {
379412
exports.DriverService = DriverService;
380413
exports.FileDetector = FileDetector;
381414
exports.SeleniumServer = SeleniumServer;
415+
exports.ServiceOptions = ServiceOptions; // Exported for API docs.

0 commit comments

Comments
 (0)