From 2b974f2139e0eb15644fb4c8e2d52fa0ba583025 Mon Sep 17 00:00:00 2001 From: Max Schmitt Date: Wed, 3 Jul 2024 10:46:33 +0200 Subject: [PATCH] docs(clock): update time types in Python/.NET (#31511) --- docs/src/api/class-clock.md | 63 +++++++++++++++++++++++ packages/playwright-core/types/types.d.ts | 6 +-- utils/doclint/documentation.js | 30 ++++++----- utils/doclint/generateApiJson.js | 5 +- utils/markdown.js | 20 +++---- 5 files changed, 94 insertions(+), 30 deletions(-) diff --git a/docs/src/api/class-clock.md b/docs/src/api/class-clock.md index 6f70e72a02f00..f2ee2433b4b34 100644 --- 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. diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 3152c067a3f28..a5496980e20d6 100644 --- 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; @@ -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; @@ -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; } diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js index 7340178b35ac5..54a2153273798 100644 --- 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} */ 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') diff --git a/utils/doclint/generateApiJson.js b/utils/doclint/generateApiJson.js index 5f2785484f32c..c0b533d97bc4a 100644 --- 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; } diff --git a/utils/markdown.js b/utils/markdown.js index 77e7343426eab..77a405192cecd 100644 --- 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'); }