chore: add python aliases

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`]

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`]

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

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.
 

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.

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 {};
 }
 
 /**

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

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;
 }
 

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];
       }