From 82923986925a6c719d5f7ff80992785fdfd452a1 Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Wed, 2 Nov 2022 13:35:51 -0700
Subject: [PATCH] docs: support custom hrefs for api links (#18514)

---
 docs/src/locators.md                      | 14 +++++++-------
 packages/playwright-core/types/types.d.ts |  2 +-
 utils/doclint/documentation.js            | 17 +++++++++--------
 3 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/docs/src/locators.md b/docs/src/locators.md
index c553b50573..f27c8676e9 100644
--- a/docs/src/locators.md
+++ b/docs/src/locators.md
@@ -10,13 +10,13 @@ a way to find element(s) on the page at any moment.
 
 These are the recommended built in locators.
 
-- [`method: Page.getByRole`] to locate by explicit and implicit accessibility attributes.
-- [`method: Page.getByText`] to locate by text content.
-- [`method: Page.getByLabel`] to locate a form control by associated label's text.
-- [`method: Page.getByPlaceholder`] to locate an input by placeholder.
-- [`method: Page.getByAltText`] to locate an element, usually image, by its text alternative.
-- [`method: Page.getByTitle`] to locate an element by its title.
-- [`method: Page.getByTestId`] to locate an element based on its `data-testid` attribute (other attribute can be configured).
+- [`method: Page.getByRole`](#locate-based-on-accessible-attributes) to locate by explicit and implicit accessibility attributes.
+- [`method: Page.getByText`](#locate-by-text) to locate by text content.
+- [`method: Page.getByLabel`](#locate-by-label-text) to locate a form control by associated label's text.
+- [`method: Page.getByPlaceholder`](#locate-by-placeholder-text) to locate an input by placeholder.
+- [`method: Page.getByAltText`](#locate-by-alt-text) to locate an element, usually image, by its text alternative.
+- [`method: Page.getByTitle`](#locate-by-title) to locate an element by its title.
+- [`method: Page.getByTestId`](#define-explicit-contract-and-use-a-data-testid-attribute) to locate an element based on its `data-testid` attribute (other attribute can be configured).
 
 ```js
 await page.getByLabel('User Name').fill('John');
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index c850dcc02d..52c20b3d48 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -2039,7 +2039,7 @@ export interface Page {
   /**
    * > NOTE: Only available for Chromium atm.
    *
-   * Browser-specific Coverage implementation. See [Coverage](#class-coverage) for more details.
+   * Browser-specific Coverage implementation. See [Coverage] for more details.
    */
   coverage: Coverage;
 
diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js
index fb25550661..8fec4827d6 100644
--- a/utils/doclint/documentation.js
+++ b/utils/doclint/documentation.js
@@ -46,8 +46,9 @@ const md = require('../markdown');
  *   clazz?: Documentation.Class,
  *   member?: Documentation.Member,
  *   param?: string,
- *   option?: string
- * }): string} Renderer
+ *   option?: string,
+ *   href?: string,
+ * }): string|undefined} Renderer
  */
 
 /**
@@ -773,13 +774,13 @@ function patchLinks(classOrMember, spec, classesMap, membersMap, linkRenderer) {
   md.visitAll(spec, node => {
     if (!node.text)
       return;
-    node.text = node.text.replace(/\[`(\w+): ([^\]]+)`\]/g, (match, p1, p2) => {
+    node.text = node.text.replace(/\[`(\w+): ([^\]]+)`\](?:\(([^)]*?)\))?/g, (match, p1, p2, href) => {
       if (['event', 'method', 'property'].includes(p1)) {
         const memberName = p1 + ': ' + p2;
         const member = membersMap.get(memberName);
         if (!member)
           throw new Error('Undefined member references: ' + match);
-        return linkRenderer({ member }) || match;
+        return linkRenderer({ member, href }) || match;
       }
       if (p1 === 'param') {
         let alias = p2;
@@ -792,16 +793,16 @@ function patchLinks(classOrMember, spec, classesMap, membersMap, linkRenderer) {
             throw new Error(`Referenced parameter ${match} not found in the parent method ${method.name} `);
           alias = param.alias;
         }
-        return linkRenderer({ param: alias }) || match;
+        return linkRenderer({ param: alias, href }) || match;
       }
       if (p1 === 'option')
-        return linkRenderer({ option: p2 }) || match;
+        return linkRenderer({ option: p2, href }) || match;
       throw new Error(`Undefined link prefix, expected event|method|property|param|option, got: ` + match);
     });
-    node.text = node.text.replace(/\[([\w]+)\]/g, (match, p1) => {
+    node.text = node.text.replace(/\[([\w]+)\](?:\(([^)]*?)\))?/g, (match, p1, href) => {
       const clazz = classesMap.get(p1);
       if (clazz)
-        return linkRenderer({ clazz }) || match;
+        return linkRenderer({ clazz, href }) || match;
       return match;
     });
   });