docs: generate method signatures in docs (microsoft#4590)

Author: pavelfeldman

docs-src/api-body.md

@@ -245,7 +245,7 @@ Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/W
 - `colorScheme` <"light"|"dark"|"no-preference">
 
 Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
-[page.emulateMedia(options)](#pageemulatemediaoptions) for more details. Defaults to '`light`'.
+[page.emulateMedia()](#pageemulatemedia) for more details. Defaults to '`light`'.
 
 ## context-option-logger
 

docs-src/api-params.md

@@ -128,7 +128,7 @@ await frame.fill('#username-input', 'John');
 
 - [class `Page`](./api.md#class-page)
 - [class `Frame`](./api.md#class-frame)
-- [page.frame(options)](./api.md#pageframeoptions)
+- [page.frame()](./api.md#pageframeframeselector)
 
 <br/>
 
@@ -226,9 +226,9 @@ await page.waitForSelector('#promo', { state: 'detached' });
 
 #### API reference
 
-- [page.click(selector[, options])](./api.md#pageclickselector-options)
-- [page.fill(selector, value[, options])](./api.md#pagefillselector-value-options)
-- [page.waitForSelector(selector[, options])](./api.md#pagewaitforselectorselector-options)
+- [page.click()](./api.md#pageclickselector-options)
+- [page.fill()](./api.md#pagefillselector-value-options)
+- [page.waitForSelector()](./api.md#pagewaitforselectorselector-options)
 
 <br/>
 
@@ -279,8 +279,8 @@ const result = await page.evaluate(() => {
 
 #### API reference
 
-- [`page.evaluate(pageFunction[, arg])`](api.md#pageevaluatepagefunction-arg)
-- [`frame.evaluate(pageFunction[, arg])`](api.md#frameevaluatepagefunction-arg)
+- [`page.evaluate()`](api.md#pageevaluatepagefunction-arg)
+- [`frame.evaluate()`](api.md#frameevaluatepagefunction-arg)
 - Evaluation argument [examples](api.md#evaluationargument)
 
 <br/>
@@ -352,7 +352,7 @@ await myArrayHandle.dispose();
 #### API reference
 - [class `JSHandle`](./api.md#class-jshandle)
 - [class `ElementHandle`](./api.md#class-elementhandle)
-- [`page.evaluateHandle`](./api.md#pageevaluatehandlepagefunction-arg)
-- [`page.$`](./api.md#pageselector)
-- [`page.$$`](./api.md#pageselector-1)
-- [`jsHandle.evaluate`](./api.md#jshandleevaluatepagefunction-arg)
+- [`page.evaluateHandle()`](./api.md#pageevaluatehandlepagefunction-arg)
+- [`page.$()`](./api.md#pageselector)
+- [`page.$$()`](./api.md#pageselector-1)
+- [`jsHandle.evaluate()`](./api.md#jshandleevaluatepagefunction-arg)

docs/api.md

@@ -39,7 +39,7 @@ All pages created in the context above will share the same device parameters.
 #### API reference
 
 - [`playwright.devices`](./api.md#playwrightdevices)
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
 
 <br/>
 
@@ -55,7 +55,7 @@ const context = await browser.newContext({
 
 #### API reference
 
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
 
 <br/>
 
@@ -81,8 +81,8 @@ const context = await browser.newContext({
 
 #### API reference
 
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
-- [`page.setViewportSize(viewportSize)`](./api.md#pagesetviewportsizeviewportsize)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
+- [`page.setViewportSize()`](./api.md#pagesetviewportsizeviewportsize)
 
 <br/>
 
@@ -98,7 +98,7 @@ const context = await browser.newContext({
 
 #### API reference
 
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
 
 <br/>
 
@@ -128,8 +128,8 @@ await context.clearPermissions();
 
 #### API reference
 
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
-- [`browserContext.grantPermissions(permissions[][, options])`](./api.md#browsercontextgrantpermissionspermissions-options)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
+- [`browserContext.grantPermissions()`](./api.md#browsercontextgrantpermissionspermissions-options)
 - [`browserContext.clearPermissions()`](./api.md#browsercontextclearpermissions)
 
 <br/>
@@ -152,8 +152,8 @@ await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 });
 
 #### API reference
 
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
-- [`browserContext.setGeolocation(geolocation)`](./api.md#browsercontextsetgeolocationgeolocation)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
+- [`browserContext.setGeolocation()`](./api.md#browsercontextsetgeolocationgeolocation)
 
 <br/>
 
@@ -182,5 +182,5 @@ await page.emulateMedia({ media: 'print' });
 
 #### API reference
 
-- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
-- [`page.emulateMedia([options])`](./api.md#pageemulatemediaoptions)
+- [`browser.newContext()`](./api.md#browsernewcontextoptions)
+- [`page.emulateMedia()`](./api.md#pageemulatemediaparams)

docs/core-concepts.md

@@ -108,20 +108,20 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel, chann
     }, options.logger);
   }
 
-  async connect(options: ConnectOptions): Promise<Browser> {
-    const logger = options.logger;
+  async connect(params: ConnectOptions): Promise<Browser> {
+    const logger = params.logger;
     return this._wrapApiCall('browserType.connect', async () => {
       const connection = new Connection();
 
-      const ws = new WebSocket(options.wsEndpoint, [], {
+      const ws = new WebSocket(params.wsEndpoint, [], {
         perMessageDeflate: false,
         maxPayload: 256 * 1024 * 1024, // 256Mb,
-        handshakeTimeout: this._timeoutSettings.timeout(options),
+        handshakeTimeout: this._timeoutSettings.timeout(params),
       });
 
       // The 'ws' module in node sometimes sends us multiple messages in a single task.
-      const waitForNextTask = options.slowMo
-        ? (cb: () => any) => setTimeout(cb, options.slowMo)
+      const waitForNextTask = params.slowMo
+        ? (cb: () => any) => setTimeout(cb, params.slowMo)
         : makeWaitForNextTask();
       connection.onmessage = message => {
         if (ws.readyState !== WebSocket.OPEN) {
@@ -137,9 +137,9 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel, chann
       });
 
       return await new Promise<Browser>(async (fulfill, reject) => {
-        if ((options as any).__testHookBeforeCreateBrowser) {
+        if ((params as any).__testHookBeforeCreateBrowser) {
           try {
-            await (options as any).__testHookBeforeCreateBrowser();
+            await (params as any).__testHookBeforeCreateBrowser();
           } catch (e) {
             reject(e);
           }

docs/emulation.md

@@ -288,9 +288,9 @@ export class Frame extends ChannelOwner<channels.FrameChannel, channels.FrameIni
     return this._detached;
   }
 
-  async addScriptTag(options: { url?: string, path?: string, content?: string, type?: string }): Promise<ElementHandle> {
+  async addScriptTag(script: { url?: string, path?: string, content?: string, type?: string }): Promise<ElementHandle> {
     return this._wrapApiCall(this._apiName('addScriptTag'), async () => {
-      const copy = { ...options };
+      const copy = { ...script };
       if (copy.path) {
         copy.content = (await fsReadFileAsync(copy.path)).toString();
         copy.content += '//# sourceURL=' + copy.path.replace(/\n/g, '');
@@ -299,9 +299,9 @@ export class Frame extends ChannelOwner<channels.FrameChannel, channels.FrameIni
     });
   }
 
-  async addStyleTag(options: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
+  async addStyleTag(style: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
     return this._wrapApiCall(this._apiName('addStyleTag'), async () => {
-      const copy = { ...options };
+      const copy = { ...style };
       if (copy.path) {
         copy.content = (await fsReadFileAsync(copy.path)).toString();
         copy.content += '/*# sourceURL=' + copy.path.replace(/\n/g, '') + '*/';

src/client/browserType.ts

@@ -215,9 +215,9 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
     return this._mainFrame;
   }
 
-  frame(options: string | { name?: string, url?: URLMatch }): Frame | null {
-    const name = isString(options) ? options : options.name;
-    const url = isObject(options) ? options.url : undefined;
+  frame(frameSelector: string | { name?: string, url?: URLMatch }): Frame | null {
+    const name = isString(frameSelector) ? frameSelector : frameSelector.name;
+    const url = isObject(frameSelector) ? frameSelector.url : undefined;
     assert(name || url, 'Either name or url matcher should be specified');
     return this.frames().find(f => {
       if (name)
@@ -298,12 +298,12 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
     return this._attributeToPage(() => this._mainFrame.$$(selector));
   }
 
-  async addScriptTag(options: { url?: string; path?: string; content?: string; type?: string; }): Promise<ElementHandle> {
-    return this._attributeToPage(() => this._mainFrame.addScriptTag(options));
+  async addScriptTag(script: { url?: string; path?: string; content?: string; type?: string; }): Promise<ElementHandle> {
+    return this._attributeToPage(() => this._mainFrame.addScriptTag(script));
   }
 
-  async addStyleTag(options: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
-    return this._attributeToPage(() => this._mainFrame.addStyleTag(options));
+  async addStyleTag(style: { url?: string; path?: string; content?: string; }): Promise<ElementHandle> {
+    return this._attributeToPage(() => this._mainFrame.addStyleTag(style));
   }
 
   async exposeFunction(name: string, playwrightFunction: Function) {
@@ -405,11 +405,11 @@ export class Page extends ChannelOwner<channels.PageChannel, channels.PageInitia
     });
   }
 
-  async emulateMedia(options: { media?: 'screen' | 'print' | null, colorScheme?: 'dark' | 'light' | 'no-preference' | null }) {
+  async emulateMedia(params: { media?: 'screen' | 'print' | null, colorScheme?: 'dark' | 'light' | 'no-preference' | null }) {
     return this._wrapApiCall('page.emulateMedia', async () => {
       await this._channel.emulateMedia({
-        media: options.media === null ? 'null' : options.media,
-        colorScheme: options.colorScheme === null ? 'null' : options.colorScheme,
+        media: params.media === null ? 'null' : params.media,
+        colorScheme: params.colorScheme === null ? 'null' : params.colorScheme,
       });
     });
   }

src/client/frame.ts

@@ -49,6 +49,7 @@ class Source {
     this._projectPath = path.relative(PROJECT_DIR, filePath);
     this._name = path.basename(filePath);
     this._text = text;
+    this._originalText = text;
     this._hasUpdatedText = false;
   }
 
@@ -75,14 +76,9 @@ class Source {
 
   /**
    * @param {string} text
-   * @return {boolean}
    */
   setText(text) {
-    if (text === this._text)
-      return false;
-    this._hasUpdatedText = true;
     this._text = text;
-    return true;
   }
 
   /**
@@ -96,7 +92,7 @@ class Source {
    * @return {boolean}
    */
   hasUpdatedText() {
-    return this._hasUpdatedText;
+    return this._text !== this._originalText;
   }
 
   async save() {

src/client/page.ts

@@ -21,7 +21,7 @@ const path = require('path');
 const os = require('os');
 const Source = require('./Source');
 const Message = require('./Message');
-const { renderMdTemplate } = require('./../parse_md');
+const { renderMdTemplate, parseMd, renderMd, parseArgument } = require('./../parse_md');
 const { spawnSync } = require('child_process');
 
 const PROJECT_DIR = path.join(__dirname, '..', '..');
@@ -45,22 +45,64 @@ async function run() {
   let changedFiles = false;
 
   // Produce api.md
+  const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
   {
     const comment = '<!-- THIS FILE IS NOW GENERATED -->';
     const header = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-header.md')).toString();
     const body = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString();
     const footer = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-footer.md')).toString();
     let params = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString();
     params = renderMdTemplate(params, params);
-    fs.writeFileSync(path.join(PROJECT_DIR, 'docs', 'api.md'), [comment, header, renderMdTemplate(body, params), footer].join('\n'));
+
+    const nodes = parseMd(renderMdTemplate(body, params));
+    let h4;
+    let args;
+    const flush = () => {
+      if (h4 && !['page.accessibility', 'page.mouse', 'page.keyboard', 'page.coverage', 'page.touchscreen'].includes(h4.h4)) {
+        const tokens = [];
+        let hasOptional = false;
+        for (const arg of args) {
+          const optional = arg.name === 'options' || arg.text.includes('Optional');
+          if (tokens.length) {
+            if (optional && !hasOptional)
+              tokens.push(`[, ${arg.name}`);
+            else
+              tokens.push(`, ${arg.name}`);
+          } else {
+            if (optional && !hasOptional)
+              tokens.push(`[${arg.name}`);
+            else
+              tokens.push(`${arg.name}`);
+          }
+          hasOptional = hasOptional || optional;
+        }
+        if (hasOptional)
+          tokens.push(']');
+        h4.h4 = `${h4.h4}(${tokens.join('')})`;
+      }
+      h4 = null;
+      args = null;
+    };
+    for (const node of nodes) {
+      if (node.h1 || node.h2 || node.h3 || node.h4)
+        flush();
+      if (node.h4) {
+        h4 = node.h4.startsWith('event:') ? null : node;
+        args = node.h4.startsWith('event:') ? null : [];
+        continue;
+      }
+      if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns')) {
+        args.push(parseArgument(node.li));
+      }
+    }
+    api.setText([comment, header, renderMd(nodes), footer].join('\n'));
   }
 
   // Documentation checks.
   {
     const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md'));
     const binReadme = await Source.readFile(path.join(PROJECT_DIR, 'bin', 'README.md'));
     const contributing = await Source.readFile(path.join(PROJECT_DIR, 'CONTRIBUTING.md'));
-    const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
     const docs = await Source.readdir(path.join(PROJECT_DIR, 'docs'), '.md');
     const mdSources = [readme, binReadme, api, contributing, ...docs];