docs: explicitly annotate methods and parameters (#4771)

docs-src/api-header.md

@@ -77,7 +77,7 @@ This object can be used to launch or connect to Chromium, returning instances of
 #### playwright.devices
 - returns: <[Object]>
 
-Returns a list of devices to be used with [`browser.newContext([options])`](#browsernewcontextoptions) or [`browser.newPage([options])`](#browsernewpageoptions). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts).
+Returns a list of devices to be used with [`method: Browser.newContext`]() or [`method: Browser.newPage`](). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts).
 
 ```js
 const { webkit, devices } = require('playwright');
@@ -99,7 +99,7 @@ const iPhone = devices['iPhone 6'];
 - returns: <[Object]>
   - `TimeoutError` <[function]> A class of [TimeoutError].
 
-Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
+Playwright methods might throw errors if they are unable to fulfill a request. For example, [`method: Page.waitForSelector`]()
 might fail if the selector doesn't match any nodes during the given timeframe.
 
 For certain types of errors Playwright uses specific error classes.

docs-src/api-params.md

@@ -13,25 +13,25 @@ When to consider operation succeeded, defaults to `load`. Events can be either:
 
 Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
 The default value can be changed by using the
-[browserContext.setDefaultNavigationTimeout()](),
-[browserContext.setDefaultTimeout()](),
-[page.setDefaultNavigationTimeout()]() or
-[page.setDefaultTimeout()]() methods.
+[`method: BrowserContext.setDefaultNavigationTimeout`](),
+[`method: BrowserContext.setDefaultTimeout`](),
+[`method: Page.setDefaultNavigationTimeout`]() or
+[`method: Page.setDefaultTimeout`]() methods.
 
 ## wait-for-timeout
 
 - `timeout` <[number]>
 
 maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default
-value can be changed by using the [browserContext.setDefaultTimeout()]().
+value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]().
 
 ## input-timeout
 
 - `timeout` <[number]>
 
 Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
-using the [browserContext.setDefaultTimeout()]() or
-[page.setDefaultTimeout()]() methods.
+using the [`method: BrowserContext.setDefaultTimeout`]() or
+[`method: Page.setDefaultTimeout`]() methods.
 
 ## input-no-wait-after
 
@@ -133,7 +133,7 @@ Defaults to `'visible'`. Can be either:
       - `value` <[string]>
 
 Populates context with given storage state. This method can be used to initialize context with logged-in information
-obtained via [browserContext.storageState()](). Either a path to the file with saved storage, or an object with the following fields:
+obtained via [`method: BrowserContext.storageState`](). Either a path to the file with saved storage, or an object with the following fields:
 
 ## context-option-acceptdownloads
 
@@ -218,7 +218,7 @@ request header value as well as number and date formatting rules.
 - `permissions` <[Array]<[string]>>
 
 A list of permissions to grant to all pages in this context. See
-[browserContext.grantPermissions()]() for more details.
+[`method: BrowserContext.grantPermissions`]() for more details.
 
 ## context-option-extrahttpheaders
 
@@ -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()]() for more details. Defaults to '`light`'.
+[`method: Page.emulateMedia`]() for more details. Defaults to '`light`'.
 
 ## context-option-logger
 
@@ -257,9 +257,9 @@ Logger sink for Playwright logging.
 
 - `videosPath` <[string]>
 
-**NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to
+**NOTE** Use [`param: recordVideo`]() instead, it takes precedence over `videosPath`. Enables video recording for all pages to
 `videosPath` directory. If not specified, videos are not recorded. Make sure to await
-[browserContext.close()]() for videos to be saved.
+[`method: BrowserContext.close`]() for videos to be saved.
 
 ## context-option-videosize
 
@@ -267,7 +267,7 @@ Logger sink for Playwright logging.
   - `width` <[number]> Video frame width.
   - `height` <[number]> Video frame height.
 
-**NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
+**NOTE** Use [`param: recordVideo`]() instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
 recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If
 `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled
 down if necessary to fit specified size.
@@ -280,7 +280,7 @@ down if necessary to fit specified size.
   - `path` <[string]> Path on the filesystem to write the HAR file to.
 
 Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not
-specified, the HAR is not recorded. Make sure to await [browserContext.close()]() for the HAR to be
+specified, the HAR is not recorded. Make sure to await [`method: BrowserContext.close`]() for the HAR to be
 saved.
 
 ## context-option-recordvideo
@@ -294,7 +294,7 @@ saved.
     - `height` <[number]> Video frame height.
 
 Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make
-sure to await [browserContext.close()]() for videos to be saved.
+sure to await [`method: BrowserContext.close`]() for videos to be saved.
 
 ## context-option-proxy
 

utils/doclint/cli.js

@@ -199,7 +199,7 @@ async function run() {
           }
         }
       }
-      api.setText([comment, header, renderMd(nodes), footer].join('\n'));
+      api.setText([comment, header, renderMd(nodes, 10000), footer].join('\n'));
 
       // Generate links
       preprocessor.generateLinks(api, signatures, messages);

utils/doclint/preprocessor/index.js

@@ -188,22 +188,32 @@ function generateLinks(source, signatures, messages) {
     let match;
     while (match = linkRegex.exec(line)) {
       const [, name] = match;
+      const linkOffset = offset + lineNumber + match.index;
       const hrefOffset = offset + lineNumber + match.index + 3 + name.length;
-      const eventMatch = name.match(/.*on\('.*'\)/);
       let replacement;
-      if (eventMatch) {
-        replacement = eventMatch[0];
-      } else {
-        const method = name.substring(0, name.length - 2);
+      const memberMatch = name.match(/`(event|method|namespace):\s(JS|CDP|[A-Z])([^.]+)\.(.*)`/m);
+      const paramMatch = name.match(/`(?:param|option):\s(.*)`/m);
+      if (!memberMatch && !paramMatch) {
+        messages.push(Message.error(`Bad link: ${source.filePath()}:${lineNumber + 1}: ${name}`));
+        return;
+      }
+      if (memberMatch && memberMatch[1] === 'event') {
+        replacement = `${memberMatch[2].toLowerCase() + memberMatch[3]}.on('${memberMatch[4]}')`;
+        sourceEdits.edit(linkOffset + 1, hrefOffset - 2, replacement);
+      } else if (memberMatch && memberMatch[1] === 'method') {
+        const method = memberMatch[2].toLowerCase() + memberMatch[3] + '.' + memberMatch[4];
         let signature = signatures.get(method);
         if (signature === undefined) {
           messages.push(Message.error(`Bad method link: ${source.filePath()}:${lineNumber + 1}: ${method}`));
-          signature = '\u2026';
+          signature = '(\u2026)';
         }
-        sourceEdits.edit(hrefOffset - 3, hrefOffset - 3, signature);
-        replacement = name + signature;
+        replacement = method + '(' + signature + ')';
+        sourceEdits.edit(linkOffset + 2, hrefOffset - 3, replacement);
+      } else if (paramMatch) {
+        sourceEdits.edit(linkOffset, hrefOffset + 1, '`' + paramMatch[1] + '`');
       }
-      sourceEdits.edit(hrefOffset, hrefOffset, '#' + replacement.toLowerCase().replace(/[^a-z]/gm, ''));
+      if (replacement)
+        sourceEdits.edit(hrefOffset, hrefOffset, '#' + replacement.toLowerCase().replace(/[^a-z]/gm, ''));
     }
     offset += line.length;
   });

utils/parse_md.js

@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-const maxColumns = 120;
-
 function normalizeLines(content) {
   const inLines = content.split('\n');
   let inCodeBlock = false;
@@ -133,23 +131,17 @@ function parseMd(content) {
   return buildTree(normalizeLines(content));
 }
 
-function renderMd(nodes) {
+function renderMd(nodes, maxColumns) {
   const result = [];
   let lastNode;
   for (let node of nodes) {
-    innerRenderMdNode(node, lastNode, result);
+    innerRenderMdNode(node, lastNode, result, maxColumns);
     lastNode = node;
   }
   return result.join('\n');
 }
 
-function renderMdNode(node, lastNode) {
-  const result = [];
-  innerRenderMdNode(node, lastNode, result);
-  return result.join('\n');
-}
-
-function innerRenderMdNode(node, lastNode, result) {
+function innerRenderMdNode(node, lastNode, result, maxColumns = 120) {
   const newLine = () => {
     if (result[result.length - 1] !== '')
       result.push('');
@@ -161,7 +153,7 @@ function innerRenderMdNode(node, lastNode, result) {
       result.push(`${'#'.repeat(i)} ${node[`h${i}`]}`);
       let lastNode = node;
       for (const child of node.children) {
-        innerRenderMdNode(child, lastNode, result);
+        innerRenderMdNode(child, lastNode, result, maxColumns);
         lastNode = child;
       }
       break;
@@ -172,7 +164,7 @@ function innerRenderMdNode(node, lastNode, result) {
     const bothComments = node.text.startsWith('>') && lastNode && lastNode.text && lastNode.text.startsWith('>');
     if (!bothComments && lastNode && (lastNode.text || lastNode.li || lastNode.h1 || lastNode.h2 || lastNode.h3 || lastNode.h4))
       newLine();
-      printText(node, result);
+      printText(node, result, maxColumns);
   }
 
   if (node.code) {
@@ -207,7 +199,7 @@ function innerRenderMdNode(node, lastNode, result) {
   }
 }
 
-function printText(node, result) {
+function printText(node, result, maxColumns) {
   let line = node.text;
   while (line.length > maxColumns) {
     let index = line.lastIndexOf(' ', maxColumns);