docs: link to the new docs from source (#5092)

docs/src/api/class-elementhandle.md

@@ -62,7 +62,7 @@ ElementHandle instances can be used as an argument in [`method: Page.$eval`] and
 - returns: <[null]|[ElementHandle]>
 
 The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See
-[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
+[Working with selectors](./selectors.md) for more details. If no elements match the selector,
 returns `null`.
 
 ### param: ElementHandle.$.selector = %%-query-selector-%%
@@ -73,7 +73,7 @@ returns `null`.
 - returns: <[Array]<[ElementHandle]>>
 
 The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See
-[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
+[Working with selectors](./selectors.md) for more details. If no elements match the selector,
 returns empty array.
 
 ### param: ElementHandle.$$.selector = %%-query-selector-%%
@@ -86,7 +86,7 @@ returns empty array.
 Returns the return value of [`param: pageFunction`]
 
 The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first
-argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md#working-with-selectors) for more
+argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for more
 details. If no elements match the selector, the method throws an error.
 
 If [`param: pageFunction`] returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its
@@ -134,7 +134,7 @@ Returns the return value of [`param: pageFunction`]
 
 The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of
 matched elements as a first argument to [`param: pageFunction`]. See
-[Working with selectors](./selectors.md#working-with-selectors) for more details.
+[Working with selectors](./selectors.md) for more details.
 
 If [`param: pageFunction`] returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its
 value.

docs/src/api/class-frame.md

@@ -82,7 +82,7 @@ with sync_playwright() as playwright:
 Returns the ElementHandle pointing to the frame element.
 
 The method finds an element matching the specified selector within the frame. See
-[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
+[Working with selectors](./selectors.md) for more details. If no elements match the selector,
 returns `null`.
 
 ### param: Frame.$.selector = %%-query-selector-%%
@@ -95,7 +95,7 @@ returns `null`.
 Returns the ElementHandles pointing to the frame elements.
 
 The method finds all elements matching the specified selector within the frame. See
-[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
+[Working with selectors](./selectors.md) for more details. If no elements match the selector,
 returns empty array.
 
 ### param: Frame.$$.selector = %%-query-selector-%%
@@ -108,7 +108,7 @@ returns empty array.
 Returns the return value of [`param: pageFunction`]
 
 The method finds an element matching the specified selector within the frame and passes it as a first argument to
-[`param: pageFunction`]. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no
+[`param: pageFunction`]. See [Working with selectors](./selectors.md) for more details. If no
 elements match the selector, the method throws an error.
 
 If [`param: pageFunction`] returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its
@@ -155,7 +155,7 @@ Optional argument to pass to [`param: pageFunction`]
 Returns the return value of [`param: pageFunction`]
 
 The method finds all elements matching the specified selector within the frame and passes an array of matched elements
-as a first argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md#working-with-selectors) for
+as a first argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for
 more details.
 
 If [`param: pageFunction`] returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its
@@ -416,9 +416,9 @@ Returns the return value of [`param: pageFunction`]
 If the function passed to the [`method: Frame.evaluate`] returns a [Promise], then [`method: Frame.evaluate`] would wait for the promise to
 resolve and return its value.
 
-If the function passed to the [`method: Frame.evaluate`] returns a non-[Serializable] value, then[ method: `Frame.evaluate`] returns
+If the function passed to the [`method: Frame.evaluate`] returns a non-[Serializable] value, then
-`undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`:
+[`method: Frame.evaluate`] returns `undefined`. DevTools Protocol also supports transferring some additional values that
-`-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
+are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
 
 ```js
 const result = await frame.evaluate(([x, y]) => {
@@ -493,11 +493,11 @@ Optional argument to pass to [`param: pageFunction`]
 
 Returns the return value of [`param: pageFunction`] as in-page object (JSHandle).
 
-The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that[ method: Fframe.evaluateHandle`] returns in-page
+The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that
-object (JSHandle).
+[method: Frame.evaluateHandle`] returns in-page object (JSHandle).
 
-If the function, passed to the [`method: Frame.evaluateHandle`], returns a [Promise], then[ method: Fframe.evaluateHandle`] would wait for
+If the function, passed to the [`method: Frame.evaluateHandle`], returns a [Promise], then
-the promise to resolve and return its value.
+[`method: Frame.evaluateHandle`] would wait for the promise to resolve and return its value.
 
 ```js
 const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
@@ -1024,7 +1024,7 @@ Returns frame's url.
 
 Returns when the [`param: pageFunction`] returns a truthy value, returns that value.
 
-The `waitForFunction` can be used to observe viewport size change:
+The [`method: Frame.waitForFunction`] can be used to observe viewport size change:
 
 ```js
 const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.

docs/src/api/class-page.md

@@ -829,12 +829,12 @@ page.evaluate("matchMedia('(prefers-color-scheme: no-preference)').matches")
 
 Returns the value of the [`param: pageFunction`] invocation.
 
-If the function passed to the [`method: Page.evaluate`] returns a [Promise], then [`method: Page.evaluate`] would wait for the promise to
+If the function passed to the [`method: Page.evaluate`] returns a [Promise], then [`method: Page.evaluate`] would wait
-resolve and return its value.
+for the promise to resolve and return its value.
 
-If the function passed to the [`method: Page.evaluate`] returns a non-[Serializable] value, then[ method: `Page.evaluate`] resolves to
+If the function passed to the [`method: Page.evaluate`] returns a non-[Serializable] value, then
-`undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`:
+[`method: Page.evaluate`] resolves to `undefined`. DevTools Protocol also supports transferring some additional values
-`-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
+that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
 
 Passing argument to [`param: pageFunction`]:
 
@@ -2206,7 +2206,7 @@ Either a predicate that receives an event or an options object. Optional.
 
 Returns when the [`param: pageFunction`] returns a truthy value. It resolves to a JSHandle of the truthy value.
 
-The `waitForFunction` can be used to observe viewport size change:
+The [`method: Page.waitForFunction`] can be used to observe viewport size change:
 
 ```js
 const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.

docs/src/api/class-playwright.md

@@ -157,7 +157,7 @@ This object can be used to launch or connect to Firefox, returning instances of
 - type: <[Selectors]>
 
 Selectors can be used to install custom selector engines. See
-[Working with selectors](./selectors.md#working-with-selectors) for more information.
+[Working with selectors](./selectors.md) for more information.
 
 ## property: Playwright.webkit
 - type: <[BrowserType]>

docs/src/api/class-selectors.md

@@ -1,7 +1,7 @@
 # class: Selectors
 
 Selectors can be used to install custom selector engines. See
-[Working with selectors](./selectors.md#working-with-selectors) for more information.
+[Working with selectors](./selectors.md) for more information.
 
 ## async method: Selectors.register
 

docs/src/api/params.md

@@ -45,7 +45,7 @@ Whether to bypass the [actionability](./actionability.md) checks. Defaults to `f
 - `selector` <[string]>
 
 A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See
-[working with selectors](./selectors.md#working-with-selectors) for more details.
+[working with selectors](./selectors.md) for more details.
 
 ## input-position
 - `position` <[Object]>
@@ -85,7 +85,7 @@ defaults to 1. See [UIEvent.detail].
 ## query-selector
 - `selector` <[string]>
 
-A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
+A selector to query for. See [working with selectors](./selectors.md) for more details.
 
 ## wait-for-selector-state
 - `state` <"attached"|"detached"|"visible"|"hidden">

utils/generate_types/index.js

@@ -39,9 +39,9 @@ let hadChanges = false;
   documentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api'));
   documentation.filterForLanguage('js');
   documentation.copyDocsFromSuperclasses([]);
-  const createMemberLink = (text) => {
+  const createMemberLink = (clazz, text) => {
     const anchor = text.toLowerCase().split(',').map(c => c.replace(/[^a-z]/g, '')).join('-');
-    return `[${text}](https://github.com/microsoft/playwright/blob/master/docs/api.md#${anchor})`;
+    return `[${text}](https://playwright.dev/docs/api/class-${clazz.name.toLowerCase()}#${anchor})`;
   };
   documentation.setLinkRenderer(item => {
     const { clazz, member, param, option } = item;
@@ -52,11 +52,11 @@ let hadChanges = false;
     if (clazz)
       return `[${clazz.name}]`;
     if (member.kind === 'method')
-      return createMemberLink(`${member.clazz.varName}.${member.name}(…)`);
+      return createMemberLink(member.clazz, `${member.clazz.varName}.${member.name}(${renderJSSignature(member.argsArray)})`);
     if (member.kind === 'event')
-      return createMemberLink(`${member.clazz.varName}.on('${member.name}')`);
+      return createMemberLink(member.clazz, `${member.clazz.varName}.on('${member.name}')`);
     if (member.kind === 'property')
-      return createMemberLink(`${member.clazz.varName}.${member.name}`);
+      return createMemberLink(member.clazz, `${member.clazz.varName}.${member.name}`);
     throw new Error('Unknown member kind ' + member.kind);
   });
   documentation.generateSourceCodeComments();
@@ -283,10 +283,9 @@ function writeComment(comment, indent = '') {
       pushLine(line);
   }
   comment = out.join('\n');
-  comment = comment.replace(/\[`([^`]+)`\]\(#([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/api.md#$2)');
+  comment = comment.replace(/\[([^\]]+)\]\(\.\/([^\)]+)\)/g, (match, p1, p2) => {
-  comment = comment.replace(/\[([^\]]+)\]\(#([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/api.md#$2)');
+    return `[${p1}](https://playwright.dev/docs/${p2.replace('.md', '')})`;
-  comment = comment.replace(/\[`([^`]+)`\]\(\.\/([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/$2)');
+  });
-  comment = comment.replace(/\[([^\]]+)\]\(\.\/([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/$2)');
 
   parts.push(indent + '/**');
   parts.push(...comment.split('\n').map(line => indent + ' * ' + line.replace(/\*\//g, '*\\/')));
@@ -392,3 +391,30 @@ ${namedDevices}
   [key: string]: DeviceDescriptor;
 }`;
 }
+
+/**
+ * @param {Documentation.Member[]} args
+ */
+function renderJSSignature(args) {
+  const tokens = [];
+  let hasOptional = false;
+  for (const arg of args) {
+    const name = arg.name;
+    const optional = !arg.required;
+    if (tokens.length) {
+      if (optional && !hasOptional)
+        tokens.push(`[, ${name}`);
+      else
+        tokens.push(`, ${name}`);
+    } else {
+      if (optional && !hasOptional)
+        tokens.push(`[${name}`);
+      else
+        tokens.push(`${name}`);
+    }
+    hasOptional = hasOptional || optional;
+  }
+  if (hasOptional)
+    tokens.push(']');
+  return tokens.join('');
+}