Skip to content

Commit 2452d07

Browse files
pavelfeldmanpavelfeldman
authored
docs: generate method signatures in docs (#4590)
1 parent 0eb6f85 commit 2452d07

File tree

12 files changed

+533
-843
lines changed

12 files changed

+533
-843
lines changed

‎docs-src/api-body.md

Lines changed: 330 additions & 679 deletions
Large diffs are not rendered by default.

‎docs-src/api-params.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/W
245245
- `colorScheme` <"light"|"dark"|"no-preference">
246246

247247
Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
248-
[page.emulateMedia(options)](#pageemulatemediaoptions) for more details. Defaults to '`light`'.
248+
[page.emulateMedia()](#pageemulatemedia) for more details. Defaults to '`light`'.
249249

250250
## context-option-logger
251251

‎docs/api.md

Lines changed: 108 additions & 109 deletions
Large diffs are not rendered by default.

‎docs/core-concepts.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ await frame.fill('#username-input', 'John');
128128

129129
- [class `Page`](./api.md#class-page)
130130
- [class `Frame`](./api.md#class-frame)
131-
- [page.frame(options)](./api.md#pageframeoptions)
131+
- [page.frame()](./api.md#pageframeframeselector)
132132

133133
<br/>
134134

@@ -226,9 +226,9 @@ await page.waitForSelector('#promo', { state: 'detached' });
226226

227227
#### API reference
228228

229-
- [page.click(selector[, options])](./api.md#pageclickselector-options)
230-
- [page.fill(selector, value[, options])](./api.md#pagefillselector-value-options)
231-
- [page.waitForSelector(selector[, options])](./api.md#pagewaitforselectorselector-options)
229+
- [page.click()](./api.md#pageclickselector-options)
230+
- [page.fill()](./api.md#pagefillselector-value-options)
231+
- [page.waitForSelector()](./api.md#pagewaitforselectorselector-options)
232232

233233
<br/>
234234

@@ -279,8 +279,8 @@ const result = await page.evaluate(() => {
279279

280280
#### API reference
281281

282-
- [`page.evaluate(pageFunction[, arg])`](api.md#pageevaluatepagefunction-arg)
283-
- [`frame.evaluate(pageFunction[, arg])`](api.md#frameevaluatepagefunction-arg)
282+
- [`page.evaluate()`](api.md#pageevaluatepagefunction-arg)
283+
- [`frame.evaluate()`](api.md#frameevaluatepagefunction-arg)
284284
- Evaluation argument [examples](api.md#evaluationargument)
285285

286286
<br/>
@@ -352,7 +352,7 @@ await myArrayHandle.dispose();
352352
#### API reference
353353
- [class `JSHandle`](./api.md#class-jshandle)
354354
- [class `ElementHandle`](./api.md#class-elementhandle)
355-
- [`page.evaluateHandle`](./api.md#pageevaluatehandlepagefunction-arg)
356-
- [`page.$`](./api.md#pageselector)
357-
- [`page.$$`](./api.md#pageselector-1)
358-
- [`jsHandle.evaluate`](./api.md#jshandleevaluatepagefunction-arg)
355+
- [`page.evaluateHandle()`](./api.md#pageevaluatehandlepagefunction-arg)
356+
- [`page.$()`](./api.md#pageselector)
357+
- [`page.$$()`](./api.md#pageselector-1)
358+
- [`jsHandle.evaluate()`](./api.md#jshandleevaluatepagefunction-arg)

‎docs/emulation.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ All pages created in the context above will share the same device parameters.
3939
#### API reference
4040

4141
- [`playwright.devices`](./api.md#playwrightdevices)
42-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
42+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
4343

4444
<br/>
4545

@@ -55,7 +55,7 @@ const context = await browser.newContext({
5555

5656
#### API reference
5757

58-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
58+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
5959

6060
<br/>
6161

@@ -81,8 +81,8 @@ const context = await browser.newContext({
8181

8282
#### API reference
8383

84-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
85-
- [`page.setViewportSize(viewportSize)`](./api.md#pagesetviewportsizeviewportsize)
84+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
85+
- [`page.setViewportSize()`](./api.md#pagesetviewportsizeviewportsize)
8686

8787
<br/>
8888

@@ -98,7 +98,7 @@ const context = await browser.newContext({
9898

9999
#### API reference
100100

101-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
101+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
102102

103103
<br/>
104104

@@ -128,8 +128,8 @@ await context.clearPermissions();
128128

129129
#### API reference
130130

131-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
132-
- [`browserContext.grantPermissions(permissions[][, options])`](./api.md#browsercontextgrantpermissionspermissions-options)
131+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
132+
- [`browserContext.grantPermissions()`](./api.md#browsercontextgrantpermissionspermissions-options)
133133
- [`browserContext.clearPermissions()`](./api.md#browsercontextclearpermissions)
134134

135135
<br/>
@@ -152,8 +152,8 @@ await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 });
152152

153153
#### API reference
154154

155-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
156-
- [`browserContext.setGeolocation(geolocation)`](./api.md#browsercontextsetgeolocationgeolocation)
155+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
156+
- [`browserContext.setGeolocation()`](./api.md#browsercontextsetgeolocationgeolocation)
157157

158158
<br/>
159159

@@ -182,5 +182,5 @@ await page.emulateMedia({ media: 'print' });
182182

183183
#### API reference
184184

185-
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
186-
- [`page.emulateMedia([options])`](./api.md#pageemulatemediaoptions)
185+
- [`browser.newContext()`](./api.md#browsernewcontextoptions)
186+
- [`page.emulateMedia()`](./api.md#pageemulatemediaparams)

‎src/client/browserType.ts

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -108,20 +108,20 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel, chann
108108
}, options.logger);
109109
}
110110

111-
async connect(options: ConnectOptions): Promise<Browser> {
112-
const logger = options.logger;
111+
async connect(params: ConnectOptions): Promise<Browser> {
112+
const logger = params.logger;
113113
return this._wrapApiCall('browserType.connect', async () => {
114114
const connection = new Connection();
115115

116-
const ws = new WebSocket(options.wsEndpoint, [], {
116+
const ws = new WebSocket(params.wsEndpoint, [], {
117117
perMessageDeflate: false,
118118
maxPayload: 256 * 1024 * 1024, // 256Mb,
119-
handshakeTimeout: this._timeoutSettings.timeout(options),
119+
handshakeTimeout: this._timeoutSettings.timeout(params),
120120
});
121121

122122
// The 'ws' module in node sometimes sends us multiple messages in a single task.
123-
const waitForNextTask = options.slowMo
124-
? (cb: () => any) => setTimeout(cb, options.slowMo)
123+
const waitForNextTask = params.slowMo
124+
? (cb: () => any) => setTimeout(cb, params.slowMo)
125125
: makeWaitForNextTask();
126126
connection.onmessage = message => {
127127
if (ws.readyState !== WebSocket.OPEN) {
@@ -137,9 +137,9 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel, chann
137137
});
138138

139139
return await new Promise<Browser>(async (fulfill, reject) => {
140-
if ((options as any).__testHookBeforeCreateBrowser) {
140+
if ((params as any).__testHookBeforeCreateBrowser) {
141141
try {
142-
await (options as any).__testHookBeforeCreateBrowser();
142+
await (params as any).__testHookBeforeCreateBrowser();
143143
} catch (e) {
144144
reject(e);
145145
}

‎src/client/frame.ts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -288,9 +288,9 @@ export class Frame extends ChannelOwner<channels.FrameChannel, channels.FrameIni
288288
return this._detached;
289289
}
290290

291-
async addScriptTag(options: { url?: string, path?: string, content?: string, type?: string }): Promise<ElementHandle> {
291+
async addScriptTag(script: { url?: string, path?: string, content?: string, type?: string }): Promise<ElementHandle> {
292292
return this._wrapApiCall(this._apiName('addScriptTag'), async () => {
293-
const copy = { ...options };
293+
const copy = { ...script };
294294
if (copy.path) {
295295
copy.content = (await fsReadFileAsync(copy.path)).toString();
296296
copy.content += '//# sourceURL=' + copy.path.replace(/\n/g, '');
@@ -299,9 +299,9 @@ export class Frame extends ChannelOwner<channels.FrameChannel, channels.FrameIni
299299
});
300300
}
301301

302-
async addStyleTag(options: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
302+
async addStyleTag(style: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
303303
return this._wrapApiCall(this._apiName('addStyleTag'), async () => {
304-
const copy = { ...options };
304+
const copy = { ...style };
305305
if (copy.path) {
306306
copy.content = (await fsReadFileAsync(copy.path)).toString();
307307
copy.content += '/*# sourceURL=' + copy.path.replace(/\n/g, '') + '*/';

‎src/client/page.ts

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -215,9 +215,9 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
215215
return this._mainFrame;
216216
}
217217

218-
frame(options: string | { name?: string, url?: URLMatch }): Frame | null {
219-
const name = isString(options) ? options : options.name;
220-
const url = isObject(options) ? options.url : undefined;
218+
frame(frameSelector: string | { name?: string, url?: URLMatch }): Frame | null {
219+
const name = isString(frameSelector) ? frameSelector : frameSelector.name;
220+
const url = isObject(frameSelector) ? frameSelector.url : undefined;
221221
assert(name || url, 'Either name or url matcher should be specified');
222222
return this.frames().find(f => {
223223
if (name)
@@ -298,12 +298,12 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
298298
return this._attributeToPage(() => this._mainFrame.$$(selector));
299299
}
300300

301-
async addScriptTag(options: { url?: string; path?: string; content?: string; type?: string; }): Promise<ElementHandle> {
302-
return this._attributeToPage(() => this._mainFrame.addScriptTag(options));
301+
async addScriptTag(script: { url?: string; path?: string; content?: string; type?: string; }): Promise<ElementHandle> {
302+
return this._attributeToPage(() => this._mainFrame.addScriptTag(script));
303303
}
304304

305-
async addStyleTag(options: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
306-
return this._attributeToPage(() => this._mainFrame.addStyleTag(options));
305+
async addStyleTag(style: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
306+
return this._attributeToPage(() => this._mainFrame.addStyleTag(style));
307307
}
308308

309309
async exposeFunction(name: string, playwrightFunction: Function) {
@@ -405,11 +405,11 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
405405
});
406406
}
407407

408-
async emulateMedia(options: { media?: 'screen' | 'print' | null, colorScheme?: 'dark' | 'light' | 'no-preference' | null }) {
408+
async emulateMedia(params: { media?: 'screen' | 'print' | null, colorScheme?: 'dark' | 'light' | 'no-preference' | null }) {
409409
return this._wrapApiCall('page.emulateMedia', async () => {
410410
await this._channel.emulateMedia({
411-
media: options.media === null ? 'null' : options.media,
412-
colorScheme: options.colorScheme === null ? 'null' : options.colorScheme,
411+
media: params.media === null ? 'null' : params.media,
412+
colorScheme: params.colorScheme === null ? 'null' : params.colorScheme,
413413
});
414414
});
415415
}

‎utils/doclint/Source.js

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ class Source {
4949
this._projectPath = path.relative(PROJECT_DIR, filePath);
5050
this._name = path.basename(filePath);
5151
this._text = text;
52+
this._originalText = text;
5253
this._hasUpdatedText = false;
5354
}
5455

@@ -75,14 +76,9 @@ class Source {
7576

7677
/**
7778
* @param {string} text
78-
* @return {boolean}
7979
*/
8080
setText(text) {
81-
if (text === this._text)
82-
return false;
83-
this._hasUpdatedText = true;
8481
this._text = text;
85-
return true;
8682
}
8783

8884
/**
@@ -96,7 +92,7 @@ class Source {
9692
* @return {boolean}
9793
*/
9894
hasUpdatedText() {
99-
return this._hasUpdatedText;
95+
return this._text !== this._originalText;
10096
}
10197

10298
async save() {

‎utils/doclint/cli.js

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ const path = require('path');
2121
const os = require('os');
2222
const Source = require('./Source');
2323
const Message = require('./Message');
24-
const { renderMdTemplate } = require('./../parse_md');
24+
const { renderMdTemplate, parseMd, renderMd, parseArgument } = require('./../parse_md');
2525
const { spawnSync } = require('child_process');
2626

2727
const PROJECT_DIR = path.join(__dirname, '..', '..');
@@ -45,22 +45,64 @@ async function run() {
4545
let changedFiles = false;
4646

4747
// Produce api.md
48+
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
4849
{
4950
const comment = '<!-- THIS FILE IS NOW GENERATED -->';
5051
const header = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-header.md')).toString();
5152
const body = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString();
5253
const footer = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-footer.md')).toString();
5354
let params = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString();
5455
params = renderMdTemplate(params, params);
55-
fs.writeFileSync(path.join(PROJECT_DIR, 'docs', 'api.md'), [comment, header, renderMdTemplate(body, params), footer].join('\n'));
56+
57+
const nodes = parseMd(renderMdTemplate(body, params));
58+
let h4;
59+
let args;
60+
const flush = () => {
61+
if (h4 && !['page.accessibility', 'page.mouse', 'page.keyboard', 'page.coverage', 'page.touchscreen'].includes(h4.h4)) {
62+
const tokens = [];
63+
let hasOptional = false;
64+
for (const arg of args) {
65+
const optional = arg.name === 'options' || arg.text.includes('Optional');
66+
if (tokens.length) {
67+
if (optional && !hasOptional)
68+
tokens.push(`[, ${arg.name}`);
69+
else
70+
tokens.push(`, ${arg.name}`);
71+
} else {
72+
if (optional && !hasOptional)
73+
tokens.push(`[${arg.name}`);
74+
else
75+
tokens.push(`${arg.name}`);
76+
}
77+
hasOptional = hasOptional || optional;
78+
}
79+
if (hasOptional)
80+
tokens.push(']');
81+
h4.h4 = `${h4.h4}(${tokens.join('')})`;
82+
}
83+
h4 = null;
84+
args = null;
85+
};
86+
for (const node of nodes) {
87+
if (node.h1 || node.h2 || node.h3 || node.h4)
88+
flush();
89+
if (node.h4) {
90+
h4 = node.h4.startsWith('event:') ? null : node;
91+
args = node.h4.startsWith('event:') ? null : [];
92+
continue;
93+
}
94+
if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns')) {
95+
args.push(parseArgument(node.li));
96+
}
97+
}
98+
api.setText([comment, header, renderMd(nodes), footer].join('\n'));
5699
}
57100

58101
// Documentation checks.
59102
{
60103
const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md'));
61104
const binReadme = await Source.readFile(path.join(PROJECT_DIR, 'bin', 'README.md'));
62105
const contributing = await Source.readFile(path.join(PROJECT_DIR, 'CONTRIBUTING.md'));
63-
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
64106
const docs = await Source.readdir(path.join(PROJECT_DIR, 'docs'), '.md');
65107
const mdSources = [readme, binReadme, api, contributing, ...docs];
66108

0 commit comments

Comments
 (0)