doc: further align docs w/ playwright.dev (3) (#4884)

docs/out/api/class-accessibility.md

@@ -36,8 +36,8 @@ Most of the accessibility tree gets filtered out when converting from Blink AX T
   - `readonly` <[boolean]> Whether the node is read only, if applicable.
   - `required` <[boolean]> Whether the node is required, if applicable.
   - `selected` <[boolean]> Whether the node is selected in its parent node, if applicable.
-  - `checked` <boolean|"mixed"> Whether the checkbox is checked, or "mixed", if applicable.
+  - `checked` <[boolean]|"mixed"> Whether the checkbox is checked, or "mixed", if applicable.
-  - `pressed` <boolean|"mixed"> Whether the toggle button is checked, or "mixed", if applicable.
+  - `pressed` <[boolean]|"mixed"> Whether the toggle button is checked, or "mixed", if applicable.
   - `level` <[number]> The level of a heading, if applicable.
   - `valuemin` <[number]> The minimum value in a node, if applicable.
   - `valuemax` <[number]> The maximum value in a node, if applicable.

utils/doclint/Documentation.js

@@ -18,6 +18,17 @@
 
 /** @typedef {import('../markdown').MarkdownNode} MarkdownNode */
 
+/**
+ * @typedef {{
+  *   name: string,
+  *   args: ParsedType | null,
+  *   retType: ParsedType | null,
+  *   template: ParsedType | null,
+  *   union: ParsedType | null,
+  *   next: ParsedType | null,
+  * }} ParsedType
+  */
+ 
 class Documentation {
   /**
    * @param {!Array<!Documentation.Class>} classesArray
@@ -242,19 +253,186 @@ Documentation.Member = class {
 };
 
 Documentation.Type = class {
+  /**
+   * @param {string} expression
+   * @param {!Array<!Documentation.Member>=} properties
+   * @return {Documentation.Type}
+   */
+  static parse(expression, properties = []) {
+    expression = expression.replace(/\\\(/g, '(').replace(/\\\)/g, ')');
+    const type = Documentation.Type.fromParsedType(parseTypeExpression(expression));
+    if (!properties.length)
+      return type;
+    const types = [];
+    type._collectAllTypes(types);
+    let success = false;
+    for (const t of types) {
+      if (t.name === 'Object') {
+        t.properties = properties;
+        success = true;
+      }
+    }
+    if (!success)
+      throw new Error('Nested properties given, but there are no objects in type expression: ' + expression);
+    return type;
+  }
+
+  /**
+   * @param {ParsedType} parsedType
+   * @return {Documentation.Type}
+   */
+  static fromParsedType(parsedType, inUnion = false) {
+    if (!inUnion && parsedType.union) {
+      const type = new Documentation.Type('union');
+      type.union = [];
+      for (let t = parsedType; t; t = t.union)
+        type.union.push(Documentation.Type.fromParsedType(t, true));
+      return type;
+    }
+
+    if (parsedType.args) {
+      const type = new Documentation.Type('function');
+      type.args = [];
+      for (let t = parsedType.args; t; t = t.next)
+        type.args.push(Documentation.Type.fromParsedType(t));
+      type.returnType = parsedType.retType ? Documentation.Type.fromParsedType(parsedType.retType) : null;
+      return type;
+    }
+
+    if (parsedType.template) {
+      const type = new Documentation.Type(parsedType.name);
+      type.templates = [];
+      for (let t = parsedType.template; t; t = t.next)
+        type.templates.push(Documentation.Type.fromParsedType(t));
+      return type;
+    }
+    return new Documentation.Type(parsedType.name);
+  }
+
   /**
    * @param {string} name
    * @param {!Array<!Documentation.Member>=} properties
    */
-  constructor(name, properties = []) {
+  constructor(name, properties) {
-    this.name = name;
+    this.name = name.replace(/^\[/, '').replace(/\]$/, '');
-    this.properties = properties;
+    this.properties = this.name === 'Object' ? properties : undefined;
+    /** @type {Documentation.Type[]} | undefined */
+    this.union;
+    /** @type {Documentation.Type[]} | undefined */
+    this.args;
+    /** @type {Documentation.Type} | undefined */
+    this.returnType;
+    /** @type {Documentation.Type[]} | undefined */
+    this.templates;
   }
 
   visit(visitor) {
-    for (const p of this.properties || [])
+    const types = [];
-      p.visit(visitor);
+    this._collectAllTypes(types);
+    for (const type of types) {
+      for (const p of type.properties || [])
+        p.visit(visitor);
+    }
+  }
+
+  /**
+   * @returns {Documentation.Member[]}
+   */
+  deepProperties() {
+    const types = [];
+    this._collectAllTypes(types);
+    for (const type of types) {
+      if (type.properties && type.properties.length)
+        return type.properties;
+    }
+    return [];
+  }
+
+  /**
+   * @param {Documentation.Type[]} result
+   */
+  _collectAllTypes(result) {
+    result.push(this);
+    for (const t of this.union || [])
+      t._collectAllTypes(result);
+    for (const t of this.args || [])
+      t._collectAllTypes(result);
+    for (const t of this.templates || [])
+      t._collectAllTypes(result);
+    if (this.returnType)
+      this.returnType._collectAllTypes(result);
   }
 };
 
+/**
+ * @param {string} type
+ * @returns {ParsedType}
+ */
+function parseTypeExpression(type) {
+  type = type.trim();
+  let name = type;
+  let next = null;
+  let template = null;
+  let args = null;
+  let retType = null;
+  let firstTypeLength = type.length;
+
+  for (let i = 0; i < type.length; i++) {
+    if (type[i] === '<') {
+      name = type.substring(0, i);
+      const matching = matchingBracket(type.substring(i), '<', '>');
+      template = parseTypeExpression(type.substring(i + 1, i + matching - 1));
+      firstTypeLength = i + matching;
+      break;
+    }
+    if (type[i] === '(') {
+      name = type.substring(0, i);
+      const matching = matchingBracket(type.substring(i), '(', ')');
+      args = parseTypeExpression(type.substring(i + 1, i + matching - 1));
+      i = i + matching;
+      if (type[i] === ':') {
+        retType = parseTypeExpression(type.substring(i + 1));
+        next = retType.next;
+        retType.next = null;
+        break;
+      }
+    }
+    if (type[i] === '|' || type[i] === ',') {
+      name = type.substring(0, i);
+      firstTypeLength = i;
+      break;
+    }
+  }
+  let union = null;
+  if (type[firstTypeLength] === '|')
+    union = parseTypeExpression(type.substring(firstTypeLength + 1));
+  else if (type[firstTypeLength] === ',')
+    next = parseTypeExpression(type.substring(firstTypeLength + 1));
+  return {
+    name,
+    args,
+    retType,
+    template,
+    union,
+    next
+  };
+}
+
+/**
+ * @param {string} str
+ * @param {any} open
+ * @param {any} close
+ */
+function matchingBracket(str, open, close) {
+  let count = 1;
+  let i = 1;
+  for (; i < str.length && count; i++) {
+    if (str[i] === open)
+      count++;
+    else if (str[i] === close)
+      count--;
+  }
+  return i;
+}
+
 module.exports = Documentation;

utils/doclint/MDBuilder.js

@@ -22,12 +22,14 @@ const Documentation = require('./Documentation');
 
 /** @typedef {import('../markdown').MarkdownNode} MarkdownNode */
 
-/** @typedef {function({
+/**
- * clazz?: Documentation.Class,
+ * @typedef {function({
- * member?: Documentation.Member,
+ *   clazz?: Documentation.Class,
- * param?: string,
+ *   member?: Documentation.Member,
- * option?: string
+ *   param?: string,
- * }): string} Renderer */
+ *   option?: string
+ * }): string} Renderer
+ */
 
 class MDOutline {
   /**
@@ -192,8 +194,12 @@ function parseMember(member) {
   }
   if (!returnType)
     returnType = new Documentation.Type('void');
-  if (match[1] === 'async method')
+
-    returnType.name = `Promise<${returnType.name}>`;
+  if (match[1] === 'async method') {
+    const templates = [ returnType ];
+    returnType = new Documentation.Type('Promise');
+    returnType.templates = templates;
+  }
 
   if (match[1] === 'event')
     return Documentation.Member.createEvent(name, returnType, extractComments(member));
@@ -234,27 +240,14 @@ function parseProperty(spec) {
  * @return {Documentation.Type}
  */
 function parseType(spec) {
-  const { type } = parseArgument(spec.text);
+  const arg = parseArgument(spec.text);
-  let typeName = type.replace(/[\[\]\\]/g, '');
-  const literals = typeName.match(/("[^"]+"(\|"[^"]+")*)/);
-  if (literals) {
-    const assorted = literals[1];
-    typeName = typeName.substring(0, literals.index) + assorted + typeName.substring(literals.index + literals[0].length);
-  }
   const properties = [];
-  const hasNonEnumProperties = typeName.split('|').some(part => {
+  for (const child of spec.children || []) {
-    const basicTypes = new Set(['string', 'number', 'boolean']);
+    const { name, text } = parseArgument(child.text);
-    const arrayTypes = new Set([...basicTypes].map(type => `Array<${type}>`));
+    const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text }]);
-    return !basicTypes.has(part) && !arrayTypes.has(part) && !(part.startsWith('"') && part.endsWith('"'));
+    properties.push(Documentation.Member.createProperty(name, parseType(child), comments, guessRequired(text)));
-  });
-  if (hasNonEnumProperties && spec) {
-    for (const child of spec.children || []) {
-      const { name, text } = parseArgument(child.text);
-      const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text }]);
-      properties.push(Documentation.Member.createProperty(name, parseType(child), comments, guessRequired(text)));
-    }
   }
-  return new Documentation.Type(typeName, properties);
+  return Documentation.Type.parse(arg.type, properties);
 }
 
 /**

utils/doclint/cli.js

@@ -268,29 +268,37 @@ function renderProperty(name, type, spec) {
   if (spec && spec.length)
     comment = spec[0].text;
   let children;
-  if (type.properties && type.properties.length)
+  const properties = type.deepProperties();
-    children = type.properties.map(p => renderProperty(`\`${p.name}\``, p.type, p.spec))
+  if (properties && properties.length)
+    children = properties.map(p => renderProperty(`\`${p.name}\``, p.type, p.spec))
   else if (spec && spec.length > 1)
     children = spec.slice(1).map(s => md.clone(s));
 
+  let typeText = renderType(type);
+  if (typeText === '[Promise]<[void]>')
+    typeText = '[Promise]';
+
   /** @type {MarkdownNode} */
   const result = {
     type: 'li',
     liType: 'default',
-    text: `${name} <${renderType(type.name)}>${comment ? ' ' + comment : ''}`,
+    text: `${name} <${typeText}>${comment ? ' ' + comment : ''}`,
     children
   };
   return result;
 }
 
 /**
- * @param {string} type
+ * @param {Documentation.Type} type
  */
 function renderType(type) {
-  if (type.includes('"'))
+  if (type.union)
-    return type.replace(/,/g, '|').replace(/Array/, "[Array]").replace(/null/, "[null]").replace(/number/, "[number]");
+    return type.union.map(l => renderType(l)).join('|');
-  const result = type.replace(/([\w]+)/g, '[$1]');
+  if (type.templates)
-  if (result === '[Promise]<[void]>')
+    return `[${type.name}]<${type.templates.map(l => renderType(l)).join(', ')}>`;
-    return '[Promise]';
+  if (type.args)
-  return result.replace(/[(]/g, '\\(').replace(/[)]/g, '\\)');
+    return `[function]\\(${type.args.map(l => renderType(l)).join(', ')}\\)${type.returnType ? ':' + renderType(type.returnType) : ''}`;
+  if (type.name.startsWith('"'))
+    return type.name;
+  return `[${type.name}]`;
 }

utils/doclint/generateApiJson.js

@@ -57,22 +57,7 @@ function serializeClass(clazz) {
     result.extends = clazz.extends;
   if (clazz.comment)
     result.comment = clazz.comment;
-  result.methods = {};
+  result.members = clazz.membersArray.map(serializeMember);
-  result.events = {};
-  result.properties = {};
-  for (const member of clazz.membersArray) {
-    let map;
-    if (member.kind === 'event') {
-      map = result.events;
-    } else if (member.kind === 'method') {
-      map = result.methods;
-    } else if (member.kind === 'property') {
-      map = result.properties;
-    } else {
-      throw new Error('Unexpected member kind: ' + member.kind + ' ' + member.name + ' ' + member.type);
-    }
-    map[member.name] = serializeMember(member);
-  }
   return result;
 }
 
@@ -82,9 +67,7 @@ function serializeClass(clazz) {
 function serializeMember(member) {
   const result = /** @type {any} */ ({ ...member });
   sanitize(result);
-  result.args = {};
+  result.args = member.argsArray.map(serializeProperty);
-  for (const arg of member.argsArray)
-    result.args[arg.name] = serializeProperty(arg);
   if (member.type)
     result.type = serializeType(member.type)
   return result;
@@ -99,27 +82,27 @@ function serializeProperty(arg) {
 }
 
 function sanitize(result) {
-  delete result.kind;
   delete result.args;
   delete result.argsArray;
-  delete result.templates;
   delete result.clazz;
-  if (result.properties && !Object.keys(result.properties).length)
+  delete result.spec;
-    delete result.properties;
-  if (result.comment === '')
-    delete result.comment;
-  if (result.returnComment === '')
-    delete result.returnComment;
 }
 
+/**
+ * @param {Documentation.Type} type
+ */
 function serializeType(type) {
+  /** @type {any} */
   const result = { ...type };
-  if (type.properties && type.properties.length) {
+  if (type.properties)
-    result.properties = {};
+    result.properties = type.properties.map(serializeProperty);
-    for (const prop of type.properties)
+  if (type.union)
-      result.properties[prop.name] = serializeProperty(prop);
+    result.union = type.union.map(serializeType);
-  } else {
+  if (type.templates)
-    delete result.properties;
+    result.templates = type.templates.map(serializeType);
-  }
+  if (type.args)
+    result.args = type.args.map(serializeType);
+  if (type.returnType)
+    result.returnType = serializeType(type.returnType);
   return result;
 }

utils/generate_types/index.js

@@ -278,19 +278,7 @@ function writeComment(comment, indent = '') {
 function stringifyComplexType(type, indent, ...namespace) {
   if (!type)
     return 'void';
-  let typeString = stringifySimpleType(parseType(type.name));
+  return stringifySimpleType(type, indent, ...namespace);
-  if (type.properties.length && typeString.indexOf('Object') !== -1) {
-    const name = namespace.map(n => n[0].toUpperCase() + n.substring(1)).join('');
-    const shouldExport = exported[name];
-    objectDefinitions.push({name, properties: type.properties});
-    if (shouldExport) {
-      typeString = typeString.replace(/Object/g, name);
-    } else {
-      const objType = stringifyObjectType(type.properties, name, indent);
-      typeString = typeString.replace(/Object/g, objType);
-    }
-  }
-  return typeString;
 }
 
 function stringifyObjectType(properties, name, indent = '') {
@@ -302,122 +290,47 @@ function stringifyObjectType(properties, name, indent = '') {
 }
 
 /**
- * @param {string} type
+ * @param {Documentation.Type=} type
+ * @returns{string}
  */
-function parseType(type) {
+function stringifySimpleType(type, indent = '', ...namespace) {
-  type = type.trim();
+  if (!type)
-  if (type.startsWith('?')) {
-    const parsed = parseType(type.substring(1));
-    parsed.nullable = true;
-    return parsed;
-  }
-  if (type.startsWith('...'))
-    return parseType('Array<' + type.substring(3) + '>');
-  let name = type;
-  let next = null;
-  let template = null;
-  let args = null;
-  let retType = null;
-  let firstTypeLength = type.length;
-  for (let i = 0; i < type.length; i++) {
-    if (type[i] === '<') {
-      name = type.substring(0, i);
-      const matching = matchingBracket(type.substring(i), '<', '>');
-      template = parseType(type.substring(i + 1, i + matching - 1));
-      firstTypeLength = i + matching;
-      break;
-    }
-    if (type[i] === '(') {
-      name = type.substring(0, i);
-      const matching = matchingBracket(type.substring(i), '(', ')');
-      args = parseType(type.substring(i + 1, i + matching - 1));
-      i = i + matching;
-      if (type[i] === ':') {
-        retType = parseType(type.substring(i + 1));
-        next = retType.next;
-        retType.next = null;
-        break;
-      }
-    }
-    if (type[i] === '|' || type[i] === ',') {
-      name = type.substring(0, i);
-      firstTypeLength = i;
-      break;
-    }
-  }
-  let pipe = null;
-  if (type[firstTypeLength] === '|')
-    pipe = parseType(type.substring(firstTypeLength + 1));
-  else if (type[firstTypeLength] === ',')
-    next = parseType(type.substring(firstTypeLength + 1));
-  if (name === 'Promise' && !template)
-    template = parseType('void');
-  return {
-    name,
-    args,
-    retType,
-    template,
-    pipe,
-    next
-  };
-}
-
-/**
- * @return {string}
- */
-function stringifySimpleType(parsedType) {
-  if (!parsedType)
     return 'void';
-  if (parsedType.name === 'Object' && parsedType.template) {
+  if (type.name === 'Object' && type.templates) {
-    const keyType = stringifySimpleType({
+    const keyType = stringifySimpleType(type.templates[0], indent, ...namespace);
-      ...parsedType.template,
+    const valueType = stringifySimpleType(type.templates[1], indent, ...namespace);
-      next: null
-    });
-    const valueType = stringifySimpleType(parsedType.template.next);
     return `{ [key: ${keyType}]: ${valueType}; }`;
   }
-  let out = parsedType.name;
+  let out = type.name;
-  if (parsedType.args) {
+  if (type.name === 'Object' && type.properties && type.properties.length) {
-    let args = parsedType.args;
+    const name = namespace.map(n => n[0].toUpperCase() + n.substring(1)).join('');
-    const stringArgs = [];
+    const shouldExport = exported[name];
-    while (args) {
+    objectDefinitions.push({name, properties: type.properties});
-      const arg = args;
+    if (shouldExport) {
-      args = args.next;
+      out = name;
-      arg.next = null;
+    } else {
-      stringArgs.push({
+      out = stringifyObjectType(type.properties, name, indent);
-        type: stringifySimpleType(arg),
-        name: arg.name.toLowerCase()
-      });
     }
-    out = `((${stringArgs.map(({name, type}) => `${name}: ${type}`).join(', ')}) => ${stringifySimpleType(parsedType.retType)})`;
+  }
-  } else if (parsedType.name === 'function') {
+
+  if (type.args) {
+    const stringArgs = type.args.map(a => ({
+      type: stringifySimpleType(a, indent, ...namespace),
+      name: a.name.toLowerCase()
+    }));
+    out = `((${stringArgs.map(({name, type}) => `${name}: ${type}`).join(', ')}) => ${stringifySimpleType(type.returnType, indent, ...namespace)})`;
+  } else if (type.name === 'function') {
     out = 'Function';
   }
   if (out === 'path')
     return 'string';
-  if (parsedType.nullable)
+  if (type.templates)
-    out = 'null|' + out;
+    out += '<' + type.templates.map(t => stringifySimpleType(t, indent, ...namespace)).join(', ') + '>';
-  if (parsedType.template)
+  if (type.union)
-    out += '<' + stringifySimpleType(parsedType.template) + '>';
+    out = type.union.map(t => stringifySimpleType(t, indent, ...namespace)).join('|');
-  if (parsedType.pipe)
-    out += '|' + stringifySimpleType(parsedType.pipe);
-  if (parsedType.next)
-    out += ', ' + stringifySimpleType(parsedType.next);
   return out.trim();
 }
 
-function matchingBracket(str, open, close) {
-  let count = 1;
-  let i = 1;
-  for (; i < str.length && count; i++) {
-    if (str[i] === open)
-      count++;
-    else if (str[i] === close)
-      count--;
-  }
-  return i;
-}
-
 /**
  * @param {Documentation.Member} member
  */