docs(clock): update time types in Python/.NET (#31511)

2024-07-03 10:46:33 +02:00 · 2024-07-03 10:46:33 +02:00 · 2b974f2139
--- a/docs/src/api/class-clock.md
+++ b/docs/src/api/class-clock.md
@ -64,11 +64,26 @@ Install fake implementations for the following time-related functions:
 Fake timers are used to manually control the flow of time in tests. They allow you to advance time, fire timers, and control the behavior of time-dependent functions. See [`method: Clock.runFor`] and [`method: Clock.fastForward`] for more information.

 ### option: Clock.install.time
+* langs: js, java
 * since: v1.45
 - `time` <[long]|[string]|[Date]>

 Time to initialize with, current system time by default.

+### option: Clock.install.time
+* langs: python
+* since: v1.45
+- `time` <[float]|[string]|[Date]>
+
+Time to initialize with, current system time by default.
+
+### option: Clock.install.time
+* langs: csharp
+* since: v1.45
+- `time` <[string]|[Date]>
+
+Time to initialize with, current system time by default.
+
 ## async method: Clock.runFor
 * since: v1.45

@ -147,9 +162,25 @@ await page.Clock.PauseAtAsync("2020-02-02");
 ```

 ### param: Clock.pauseAt.time
+* langs: js, java
 * since: v1.45
 - `time` <[long]|[string]|[Date]>

+Time to pause at.
+
+### param: Clock.pauseAt.time
+* langs: python
+* since: v1.45
+- `time` <[float]|[string]|[Date]>
+
+Time to pause at.
+
+### param: Clock.pauseAt.time
+* langs: csharp
+* since: v1.45
+- `time` <[Date]|[string]>
+
+Time to pause at.

 ## async method: Clock.resume
 * since: v1.45
@ -195,9 +226,24 @@ await page.Clock.SetFixedTimeAsync("2020-02-02");
 ```

 ### param: Clock.setFixedTime.time
+* langs: js, java
 * since: v1.45
 - `time` <[long]|[string]|[Date]>

+Time to be set in milliseconds.
+
+### param: Clock.setFixedTime.time
+* langs: python
+* since: v1.45
+- `time` <[float]|[string]|[Date]>
+
+Time to be set.
+
+### param: Clock.setFixedTime.time
+* langs: csharp
+* since: v1.45
+- `time` <[string]|[Date]>
+
 Time to be set.

 ## async method: Clock.setSystemTime
@ -238,5 +284,22 @@ await page.Clock.SetSystemTimeAsync("2020-02-02");
 ```

 ### param: Clock.setSystemTime.time
+* langs: js, java
 * since: v1.45
 - `time` <[long]|[string]|[Date]>
+
+Time to be set in milliseconds.
+
+### param: Clock.setSystemTime.time
+* langs: python
+* since: v1.45
+- `time` <[float]|[string]|[Date]>
+
+Time to be set.
+
+### param: Clock.setSystemTime.time
+* langs: csharp
+* since: v1.45
+- `time` <[string]|[Date]>
+
+Time to be set.
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@ -17287,7 +17287,7 @@ export interface Clock {
   * await page.clock.pauseAt('2020-02-02');
   * ```
   *
-   * @param time
+   * @param time Time to pause at.
   */
  pauseAt(time: number|string|Date): Promise<void>;

@ -17322,7 +17322,7 @@ export interface Clock {
   * await page.clock.setFixedTime('2020-02-02');
   * ```
   *
-   * @param time Time to be set.
+   * @param time Time to be set in milliseconds.
   */
  setFixedTime(time: number|string|Date): Promise<void>;

@ -17337,7 +17337,7 @@ export interface Clock {
   * await page.clock.setSystemTime('2020-02-02');
   * ```
   *
-   * @param time
+   * @param time Time to be set in milliseconds.
   */
  setSystemTime(time: number|string|Date): Promise<void>;
 }
--- a/utils/doclint/documentation.js
+++ b/utils/doclint/documentation.js
@ -167,7 +167,7 @@ class Documentation {
  renderLinksInNodes(nodes, classOrMember) {
    if (classOrMember instanceof Member) {
      classOrMember.discouraged = classOrMember.discouraged ? this.renderLinksInText(classOrMember.discouraged, classOrMember) : undefined;
-      classOrMember.deprecated = classOrMember.deprecated ? this.renderLinksInText(classOrMember.deprecated, classOrMember) : undefined
+      classOrMember.deprecated = classOrMember.deprecated ? this.renderLinksInText(classOrMember.deprecated, classOrMember) : undefined;
    }
    md.visitAll(nodes, node => {
      if (!node.text)
@ -208,7 +208,7 @@ class Documentation {
  }
 }

- class Class {
+class Class {
  /**
   * @param {Metainfo} metainfo
   * @param {string} name
@ -322,7 +322,7 @@ class Documentation {
    for (const e of this.eventsArray)
      e.visit(visitor);
  }
-};
+}

 class Member {
  /**
@ -345,7 +345,7 @@ class Member {
    this.spec = spec;
    this.argsArray = argsArray;
    this.required = required;
-    this.comment =  '';
+    this.comment = '';
    /** @type {!Map<string, !Member>} */
    this.args = new Map();
    this.index();
@ -473,8 +473,10 @@ class Member {
      this.type.visit(visitor);
    for (const arg of this.argsArray)
      arg.visit(visitor);
+    for (const lang in this.langs.overrides || {})
+      this.langs.overrides?.[lang].visit(visitor);
  }
-};
+}

 class Type {
  /**
@ -509,9 +511,9 @@ class Type {
   * @return {Type}
   */
  static fromParsedType(parsedType, inUnion = false) {
-    if (!inUnion && !parsedType.unionName && isStringUnion(parsedType) ) {
+    if (!inUnion && !parsedType.unionName && isStringUnion(parsedType))
      throw new Error('Enum must have a name:\n' + JSON.stringify(parsedType, null, 2));
-    }
+

    if (!inUnion && (parsedType.union || parsedType.unionName)) {
      const type = new Type(parsedType.unionName || '');
@ -556,15 +558,15 @@ class Type {
    /** @type {Member[] | undefined} */
    this.properties = this.name === 'Object' ? properties : undefined;
    /** @type {Type[] | undefined} */
-    this.union;
+    this.union = undefined;
    /** @type {Type[] | undefined} */
-    this.args;
+    this.args = undefined;
    /** @type {Type | undefined} */
-    this.returnType;
+    this.returnType = undefined;
    /** @type {Type[] | undefined} */
-    this.templates;
+    this.templates = undefined;
    /** @type {string | undefined} */
-    this.expression;
+    this.expression = undefined;
  }

  visit(visitor) {
@ -645,7 +647,7 @@ class Type {
    if (this.returnType)
      this.returnType._collectAllTypes(result);
  }
-};
+}

 /**
 * @param {ParsedType | null} type
@ -931,7 +933,7 @@ function processCodeGroups(spec, language, transformer) {
 * @param {string} codeLang
 * @return {{ highlighter: string, language: string|undefined, codeGroup: string|undefined}}
 */
- function parseCodeLang(codeLang) {
+function parseCodeLang(codeLang) {
  if (codeLang === 'python async')
    return { highlighter: 'py', codeGroup: 'python-async', language: 'python' };
  if (codeLang === 'python sync')
--- a/utils/doclint/generateApiJson.js
+++ b/utils/doclint/generateApiJson.js
@ -17,7 +17,6 @@
 // @ts-check

 const path = require('path');
-const fs = require('fs');
 const Documentation = require('./documentation');
 const { parseApi } = require('./api_parser');
 const PROJECT_DIR = path.join(__dirname, '..', '..');
@ -73,7 +72,7 @@ function serializeMember(member) {
  sanitize(result);
  result.args = member.argsArray.map(serializeProperty);
  if (member.type)
-    result.type = serializeType(member.type)
+    result.type = serializeType(member.type);
  return result;
 }

@ -81,7 +80,7 @@ function serializeProperty(arg) {
  const result = { ...arg };
  sanitize(result);
  if (arg.type)
-    result.type = serializeType(arg.type, arg.name === 'options')
+    result.type = serializeType(arg.type, arg.name === 'options');
  return result;
 }

--- a/utils/markdown.js
+++ b/utils/markdown.js
@ -124,7 +124,7 @@ function buildTree(lines) {
  const headerStack = [root];

  /** @type {{ indent: string, node: MarkdownNode }[]} */
-  let sectionStack = [];
+  const sectionStack = [];

  /**
   * @param {string} indent
@ -133,7 +133,7 @@ function buildTree(lines) {
  const appendNode = (indent, node) => {
    while (sectionStack.length && sectionStack[0].indent.length >= indent.length)
      sectionStack.shift();
-    const parentNode = sectionStack.length ? sectionStack[0].node :headerStack[0];
+    const parentNode = sectionStack.length ? sectionStack[0].node : headerStack[0];
    if (!parentNode.children)
      parentNode.children = [];
    parentNode.children.push(node);
@ -176,7 +176,7 @@ function buildTree(lines) {
      line = lines[++i];
      while (!line.trim().startsWith('```')) {
        if (line && !line.startsWith(indent)) {
-          const from = Math.max(0, i - 5)
+          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')}`);
@ -200,7 +200,7 @@ function buildTree(lines) {
      const tokens = [];
      while (!line.trim().startsWith(':::')) {
        if (!line.startsWith(indent)) {
-          const from = Math.max(0, i - 5)
+          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 comment block: ${snippet.join('\n')}`);
@ -254,7 +254,7 @@ function buildTree(lines) {
 }

 /**
- * @param {String} firstLine 
+ * @param {String} firstLine
 * @returns {[string, string|undefined]}
 */
 function parseCodeBlockMetadata(firstLine) {
@ -279,7 +279,7 @@ function parse(content) {
 function render(nodes, options) {
  const result = [];
  let lastNode;
-  for (let node of nodes) {
+  for (const node of nodes) {
    if (node.type === 'null')
      continue;
    innerRenderMdNode('', node, /** @type {MarkdownNode} */ (lastNode), result, options);
@ -322,7 +322,7 @@ function innerRenderMdNode(indent, node, lastNode, result, options) {
    const bothLinks = node.text.match(/\[[^\]]+\]:/) && lastNode && lastNode.type === 'text' && lastNode.text.match(/\[[^\]]+\]:/);
    if (!bothTables && !bothGen && !bothComments && !bothLinks && lastNode && lastNode.text)
      newLine();
-      result.push(wrapText(node.text, options, indent));
+    result.push(wrapText(node.text, options, indent));
    return;
  }

@ -391,15 +391,15 @@ function tokenizeNoBreakLinks(text) {
 * @param {string} prefix
 * @returns {string}
 */
- function wrapText(text, options, prefix) {
+function wrapText(text, options, prefix) {
  if (options?.flattenText)
    text = text.replace(/↵/g, ' ');
  const lines = text.split(/[\n↵]/);
  const result = /** @type {string[]} */([]);
  const indent = ' '.repeat(prefix.length);
-  for (const line of lines) {
+  for (const line of lines)
    result.push(wrapLine(line, options?.maxColumns, result.length ? indent : prefix));
-  }
+
  return result.join('\n');
 }