From 114d586f071b767ad2f2bd7adf25001bb2566f24 Mon Sep 17 00:00:00 2001
From: Pavel Feldman <pavel.feldman@gmail.com>
Date: Fri, 8 Jan 2021 15:00:14 -0800
Subject: [PATCH] chore: add python aliases (#4949)

---
 docs/src/api/class-browsercontext.md   |  1 +
 docs/src/api/class-elementhandle.md    |  8 +++++++
 docs/src/api/class-frame.md            |  8 +++++++
 docs/src/api/class-page.md             | 10 ++++++++
 docs/src/api/class-route.md            |  2 ++
 docs/src/api/class-websocket.md        |  1 +
 docs/src/api/params.md                 | 13 +++++++++++
 docs/src/api/python.md                 | 23 ++++++++++++++++++
 docs/src/selectors.md                  | 12 ++++++----
 utils/doclint/api_parser.js            | 28 ++++++++++++++++------
 utils/doclint/documentation.js         | 32 ++++++++++++++++++--------
 utils/doclint/generateApiJson.js       |  8 +------
 utils/doclint/missingDocs.js           |  2 +-
 utils/doclint/test/missingDocs.spec.js |  1 -
 utils/markdown.js                      | 10 +++++---
 15 files changed, 125 insertions(+), 34 deletions(-)

diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md
index 8f4418464c654..8301c0dc31f5a 100644
--- a/docs/src/api/class-browsercontext.md
+++ b/docs/src/api/class-browsercontext.md
@@ -481,6 +481,7 @@ await context.grantPermissions(['geolocation']);
 Event name, same one would pass into `browserContext.on(event)`.
 
 ### param: BrowserContext.waitForEvent.optionsOrPredicate
+* langs: js
 - `optionsOrPredicate` <[Function]|[Object]>
   - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve.
   - `timeout` <[float]> 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 [`method: BrowserContext.setDefaultTimeout`].
diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md
index 0a52a917b07c8..223fa7aa5ea43 100644
--- a/docs/src/api/class-elementhandle.md
+++ b/docs/src/api/class-elementhandle.md
@@ -22,6 +22,8 @@ JSHandle.dispose`]. ElementHandles are auto-disposed when their origin frame get
 ElementHandle instances can be used as an argument in [`method: Page.$eval`] and [`method: Page.evaluate`] methods.
 
 ## async method: ElementHandle.$
+* langs:
+  - alias-python: query_selector
 - returns: <[null]|[ElementHandle]>
 
 The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See [Working with
@@ -30,6 +32,8 @@ selectors](./selectors.md#working-with-selectors) for more details. If no elemen
 ### param: ElementHandle.$.selector = %%-query-selector-%%
 
 ## async method: ElementHandle.$$
+* langs:
+  - alias-python: query_selector_all
 - returns: <[Array]<[ElementHandle]>>
 
 The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See [Working with
@@ -38,6 +42,8 @@ selectors](./selectors.md#working-with-selectors) for more details. If no elemen
 ### param: ElementHandle.$$.selector = %%-query-selector-%%
 
 ## async method: ElementHandle.$eval
+* langs:
+  - alias-python: eval_on_selector
 - returns: <[Serializable]>
 
 Returns the return value of [`param: pageFunction`]
@@ -70,6 +76,8 @@ Function to be evaluated in browser context
 Optional argument to pass to [`param: pageFunction`]
 
 ## async method: ElementHandle.$$eval
+* langs:
+  - alias-python: eval_on_selector_all
 - returns: <[Serializable]>
 
 Returns the return value of [`param: pageFunction`]
diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md
index 86b884c9395b5..e51f30fe7e19a 100644
--- a/docs/src/api/class-frame.md
+++ b/docs/src/api/class-frame.md
@@ -38,6 +38,8 @@ console.log(text);
 ```
 
 ## async method: Frame.$
+* langs:
+  - alias-python: query_selector
 - returns: <[null]|[ElementHandle]>
 
 Returns the ElementHandle pointing to the frame element.
@@ -48,6 +50,8 @@ selectors](./selectors.md#working-with-selectors) for more details. If no elemen
 ### param: Frame.$.selector = %%-query-selector-%%
 
 ## async method: Frame.$$
+* langs:
+  - alias-python: query_selector_all
 - returns: <[Array]<[ElementHandle]>>
 
 Returns the ElementHandles pointing to the frame elements.
@@ -58,6 +62,8 @@ selectors](./selectors.md#working-with-selectors) for more details. If no elemen
 ### param: Frame.$$.selector = %%-query-selector-%%
 
 ## async method: Frame.$eval
+* langs:
+  - alias-python: eval_on_selector
 - returns: <[Serializable]>
 
 Returns the return value of [`param: pageFunction`]
@@ -90,6 +96,8 @@ Function to be evaluated in browser context
 Optional argument to pass to [`param: pageFunction`]
 
 ## async method: Frame.$$eval
+* langs:
+  - alias-python: eval_on_selector_all
 - returns: <[Serializable]>
 
 Returns the return value of [`param: pageFunction`]
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 11f680dfcd6e1..ea67a9e875a92 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -210,6 +210,8 @@ Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/We
 page.
 
 ## async method: Page.$
+* langs:
+  - alias-python: query_selector
 - returns: <[null]|[ElementHandle]>
 
 The method finds an element matching the specified selector within the page. If no elements match the selector, the
@@ -220,6 +222,8 @@ Shortcut for main frame's [`method: Frame.$`].
 ### param: Page.$.selector = %%-query-selector-%%
 
 ## async method: Page.$$
+* langs:
+  - alias-python: query_selector_all
 - returns: <[Array]<[ElementHandle]>>
 
 The method finds all elements matching the specified selector within the page. If no elements match the selector, the
@@ -230,6 +234,8 @@ Shortcut for main frame's [`method: Frame.$$`].
 ### param: Page.$$.selector = %%-query-selector-%%
 
 ## async method: Page.$eval
+* langs:
+  - alias-python: eval_on_selector
 - returns: <[Serializable]>
 
 The method finds an element matching the specified selector within the page and passes it as a first argument to
@@ -262,6 +268,8 @@ Function to be evaluated in browser context
 Optional argument to pass to [`param: pageFunction`]
 
 ## async method: Page.$$eval
+* langs:
+  - alias-python: eval_on_selector_all
 - returns: <[Serializable]>
 
 The method finds all elements matching the specified selector within the page and passes an array of matched elements as
@@ -560,6 +568,7 @@ await page.evaluate(() => matchMedia('(prefers-color-scheme: no-preference)').ma
 ```
 
 ### param: Page.emulateMedia.params
+* langs: js
 - `params` <[Object]>
   - `media` <[null]|"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. Optional.
   - `colorScheme` <[null]|"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. Optional.
@@ -1569,6 +1578,7 @@ value. Will throw an error if the page is closed before the event is fired.
 Event name, same one would pass into `page.on(event)`.
 
 ### param: Page.waitForEvent.optionsOrPredicate
+* langs: js
 - `optionsOrPredicate` <[Function]|[Object]>
   - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve.
   - `timeout` <[float]> 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 [`method: BrowserContext.setDefaultTimeout`].
diff --git a/docs/src/api/class-route.md b/docs/src/api/class-route.md
index 159311dfbabda..0b21cd3a966d9 100644
--- a/docs/src/api/class-route.md
+++ b/docs/src/api/class-route.md
@@ -27,6 +27,8 @@ Optional error code. Defaults to `failed`, could be one of the following:
   * `'failed'` - A generic failure occurred.
 
 ## async method: Route.continue
+* langs:
+  - alias-python: continue_
 
 Continues route's request with optional overrides.
 
diff --git a/docs/src/api/class-websocket.md b/docs/src/api/class-websocket.md
index f51ae99f95544..c9574e3c77ba9 100644
--- a/docs/src/api/class-websocket.md
+++ b/docs/src/api/class-websocket.md
@@ -47,6 +47,7 @@ value. Will throw an error if the webSocket is closed before the event is fired.
 Event name, same one would pass into `webSocket.on(event)`.
 
 ### param: WebSocket.waitForEvent.optionsOrPredicate
+* langs: js
 - `optionsOrPredicate` <[Function]|[Object]>
   - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve.
   - `timeout` <[float]> 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 [`method: BrowserContext.setDefaultTimeout`].
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index 7f3464d54edc1..5c4661003fe65 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -303,6 +303,19 @@ only the first option matching one of the passed options is selected. Optional.
 Options to select by label. If the `<select>` has the `multiple` attribute, all given options are selected, otherwise
 only the first option matching one of the passed options is selected. Optional.
 
+## python-wait-for-event-predicate
+* langs: python
+- `predicate` <[Function]>
+
+Receives the event data and resolves to truthy value when the waiting should resolve.
+
+## python-wait-for-event-timeout
+* langs: python
+- `timeout` <[float]>
+
+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 [`method: BrowserContext.setDefaultTimeout`].
+
 
 ## shared-context-params-list
 - %%-context-option-acceptdownloads-%%
diff --git a/docs/src/api/python.md b/docs/src/api/python.md
index e96245c8cb6ab..ee4dc404cb0e9 100644
--- a/docs/src/api/python.md
+++ b/docs/src/api/python.md
@@ -79,3 +79,26 @@ Longitude between -180 and 180. **required**
 - `accuracy` <[float]>
 
 Non-negative accuracy value. Defaults to `0`. Optional.
+
+### param: Page.emulateMedia.params
+* langs: python
+- `media` <[null]|"screen"|"print">
+
+Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`.
+Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value.
+Optional.
+
+### param: Page.emulateMedia.params
+* langs: python
+- `colorScheme` <[null]|"light"|"dark"|"no-preference">
+
+Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing
+`null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated
+value. Optional.
+
+### option: BrowserContext.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%
+### option: BrowserContext.waitForEvent.timeout = %%-python-wait-for-event-timeout-%%
+### option: Page.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%
+### option: Page.waitForEvent.timeout = %%-python-wait-for-event-timeout-%%
+### option: WebSocket.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%
+### option: WebSocket.waitForEvent.timeout = %%-python-wait-for-event-timeout-%%
diff --git a/docs/src/selectors.md b/docs/src/selectors.md
index 7b04d17bb75bf..c0871f37302b2 100644
--- a/docs/src/selectors.md
+++ b/docs/src/selectors.md
@@ -207,15 +207,17 @@ Consider a page with two buttons, first invisible and second visible.
 <button>Visible</button>
 ```
 
-* ```js
+* This will find the first button, because it is the first one in DOM order. Then it will wait for the button to become visible before clicking, or timeout while waiting:
+
+  ```js
   await page.click('button');
   ```
-  This will find the first button, because it is the first one in DOM order. Then it will wait for the button to become visible before clicking, or timeout while waiting.
 
-* ```js
+* This will find a second button, because it is visible, and then click it.
+
+  ```js
   await page.click('button:visible');
-  ```
-  This will find a second button, because it is visible, and then click it.
+  ``` 
 
 Use `:visible` with caution, because it has two major drawbacks:
 * When elements change their visibility dynamically, `:visible` will give upredictable results based on the timing.
diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js
index b8cffad02411b..c6dbb6807bfff 100644
--- a/utils/doclint/api_parser.js
+++ b/utils/doclint/api_parser.js
@@ -113,7 +113,7 @@ class ApiParser {
       let options = method.argsArray.find(o => o.name === 'options');
       if (!options) {
         const type = new Documentation.Type('Object', []);
-        options = Documentation.Member.createProperty(null, 'options', type, undefined, false);
+        options = Documentation.Member.createProperty({}, 'options', type, undefined, false);
         method.argsArray.push(options);
       }
       const p = this.parseProperty(spec);
@@ -143,7 +143,7 @@ class ApiParser {
     for (const child of spec.children || []) {
       const { name, text } = parseVariable(child.text);
       const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text }]);
-      properties.push(Documentation.Member.createProperty(null, name, this.parseType(child), comments, guessRequired(text)));
+      properties.push(Documentation.Member.createProperty({}, name, this.parseType(child), comments, guessRequired(text)));
     }
     return Documentation.Type.parse(arg.type, properties);
   }
@@ -272,13 +272,27 @@ function parseApi(apiDir) {
 
 /**
  * @param {MarkdownNode} spec
- * @returns {?Set<string>}
+ * @returns {import('./documentation').Langs}
  */
 function extractLangs(spec) {
-  for (const child of spec.children)
-  if (child.type === 'li' && child.liType === 'bullet' && child.text.startsWith('langs: '))
-    return new Set(child.text.substring('langs: '.length).split(',').map(l => l.trim()));
-  return null;
+  for (const child of spec.children) {
+    if (child.type !== 'li' || child.liType !== 'bullet' || !child.text.startsWith('langs:'))
+      continue;
+
+    const only = child.text.substring('langs:'.length).trim();
+    /** @type {Object<string, string>} */
+    const aliases = {};
+    for (const p of child.children || []) {
+      const match = p.text.match(/alias-(\w+)[\s]*:(.*)/);
+      if (match)
+        aliases[match[1].trim()] = match[2].trim();
+    }
+    return {
+      only: only ? only.split(',') : undefined,
+      aliases
+    };
+  }
+  return {};
 }
 
 /**
diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js
index 897c5eb040f39..ba4dc7a24222a 100644
--- a/utils/doclint/documentation.js
+++ b/utils/doclint/documentation.js
@@ -31,6 +31,13 @@ const md = require('../markdown');
   * }} ParsedType
   */
 
+/**
+ * @typedef {{
+ *   only?: string[],
+ *   aliases?: Object<string, string>
+ * }} Langs
+ */
+
 /**
  * @typedef {function({
   *   clazz?: Documentation.Class,
@@ -81,7 +88,7 @@ class Documentation {
   filterForLanguage(lang) {
     const classesArray = [];
     for (const clazz of this.classesArray) {
-      if (clazz.langs && !clazz.langs.has(lang))
+      if (clazz.langs.only && !clazz.langs.only.includes(lang))
         continue;
       clazz.filterForLanguage(lang);
       classesArray.push(clazz);
@@ -131,7 +138,7 @@ class Documentation {
 
 Documentation.Class = class {
   /**
-   * @param {?Set<string>} langs
+   * @param {Langs} langs
    * @param {string} name
    * @param {!Array<!Documentation.Member>} membersArray
    * @param {?string=} extendsName
@@ -188,8 +195,10 @@ Documentation.Class = class {
   filterForLanguage(lang) {
     const membersArray = [];
     for (const member of this.membersArray) {
-      if (member.langs && !member.langs.has(lang))
+      if (member.langs.only && !member.langs.only.includes(lang))
         continue;
+      if (member.langs.aliases && member.langs.aliases[lang])
+        member.alias = member.langs.aliases[lang];
       member.filterForLanguage(lang);
       membersArray.push(member);
     }
@@ -257,7 +266,7 @@ Documentation.Class = class {
 Documentation.Member = class {
   /**
    * @param {string} kind
-   * @param {?Set<string>} langs
+   * @param {Langs} langs
    * @param {string} name
    * @param {?Documentation.Type} type
    * @param {!Array<!Documentation.Member>} argsArray
@@ -287,6 +296,7 @@ Documentation.Member = class {
       });
     };
     this.async = false;
+    this.alias = name;
   }
 
   index() {
@@ -304,8 +314,10 @@ Documentation.Member = class {
   filterForLanguage(lang) {
     const argsArray = [];
     for (const arg of this.argsArray) {
-      if (arg.langs && !arg.langs.has(lang))
+      if (arg.langs.only && !arg.langs.only.includes(lang))
         continue;
+      if (arg.langs.aliases && arg.langs.aliases[lang])
+        arg.alias = arg.langs.aliases[lang];
       arg.filterForLanguage(lang);
       argsArray.push(arg);
     }
@@ -319,7 +331,7 @@ Documentation.Member = class {
   }
 
   /**
-   * @param {?Set<string>} langs
+   * @param {Langs} langs
    * @param {string} name
    * @param {!Array<!Documentation.Member>} argsArray
    * @param {?Documentation.Type} returnType
@@ -331,10 +343,10 @@ Documentation.Member = class {
   }
 
   /**
-   * @param {?Set<string>} langs
-   * @param {string} name
+   * @param {!Langs} langs
+   * @param {!string} name
    * @param {!Documentation.Type} type
-   * @param {MarkdownNode[]=} spec
+   * @param {!MarkdownNode[]=} spec
    * @param {boolean=} required
    * @return {!Documentation.Member}
    */
@@ -343,7 +355,7 @@ Documentation.Member = class {
   }
 
   /**
-   * @param {?Set<string>} langs
+   * @param {Langs} langs
    * @param {string} name
    * @param {?Documentation.Type=} type
    * @param {MarkdownNode[]=} spec
diff --git a/utils/doclint/generateApiJson.js b/utils/doclint/generateApiJson.js
index fe587efc2a055..4eeae947b31e5 100644
--- a/utils/doclint/generateApiJson.js
+++ b/utils/doclint/generateApiJson.js
@@ -52,8 +52,7 @@ function serializeClass(clazz) {
   const result = { name: clazz.name };
   if (clazz.extends)
     result.extends = clazz.extends;
-  if (clazz.langs)
-    result.langs = [...clazz.langs];
+  result.langs = clazz.langs;
   if (clazz.comment)
     result.comment = clazz.comment;
   result.members = clazz.membersArray.map(serializeMember);
@@ -66,8 +65,6 @@ function serializeClass(clazz) {
 function serializeMember(member) {
   const result = /** @type {any} */ ({ ...member });
   sanitize(result);
-  if (member.langs)
-    result.langs = [...member.langs];
   result.args = member.argsArray.map(serializeProperty);
   if (member.type)
     result.type = serializeType(member.type)
@@ -77,8 +74,6 @@ function serializeMember(member) {
 function serializeProperty(arg) {
   const result = { ...arg };
   sanitize(result);
-  if (arg.langs)
-    result.langs = [...arg.langs];
   if (arg.type)
     result.type = serializeType(arg.type)
   return result;
@@ -88,7 +83,6 @@ function sanitize(result) {
   delete result.args;
   delete result.argsArray;
   delete result.clazz;
-  delete result.langs;
   delete result.spec;
 }
 
diff --git a/utils/doclint/missingDocs.js b/utils/doclint/missingDocs.js
index 1dddfc5a2c301..42d4393f8e5b9 100644
--- a/utils/doclint/missingDocs.js
+++ b/utils/doclint/missingDocs.js
@@ -60,7 +60,7 @@ module.exports = function lint(documentation, jsSources, apiFileName) {
       }
       const memberParams = paramsForMember(member);
       for (const paramName of memberParams) {
-        if (!params.has(paramName))
+        if (!params.has(paramName) && paramName !== 'options')
           errors.push(`Documented "${cls.name}.${member.name}.${paramName}" not found is sources`);
       }
     }
diff --git a/utils/doclint/test/missingDocs.spec.js b/utils/doclint/test/missingDocs.spec.js
index 348fbada65cc7..ab2087a6f02a4 100644
--- a/utils/doclint/test/missingDocs.spec.js
+++ b/utils/doclint/test/missingDocs.spec.js
@@ -38,6 +38,5 @@ test('missing docs', async ({}) => {
     'Documented "DoesNotExist" not found in sources',
     'Documented "Exists.doesNotExist" not found is sources',
     'Documented "Exists.exists.doesNotExist" not found is sources',
-    'Documented "Exists.exists.options" not found is sources',
   ]);
 });
diff --git a/utils/markdown.js b/utils/markdown.js
index 2ec81708b48b8..fb092fbb1b31a 100644
--- a/utils/markdown.js
+++ b/utils/markdown.js
@@ -26,7 +26,7 @@
  *  }} MarkdownNode */
 
 function flattenWrappedLines(content) {
-  const inLines = content.split('\n');
+  const inLines = content.replace(/\r\n/g, '\n').split('\n');
   let inCodeBlock = false;
   const outLines = [];
   let outLineTokens = [];
@@ -124,8 +124,12 @@ function buildTree(lines) {
       };
       line = lines[++i];
       while (!line.trim().startsWith('```')) {
-        if (!line.startsWith(indent))
-          throw new Error('Bad code block ' + line);
+        if (!line.startsWith(indent)) {
+          const from = Math.max(0, i - 5)
+          const to = Math.min(lines.length, from + 10);
+          const snippet = lines.slice(from, to);
+          throw new Error(`Bad code block: ${snippet.join('\n')}`);
+        }
         node.lines.push(line.substring(indent.length));
         line = lines[++i];
       }