Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Force GitHub README to respect dark mode (function() { var style = document.createElement('style'); style.textContent = ' .markdown-body { color-scheme: dark light; } .markdown-body pre { background: #161b22 !important; } .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; } .markdown-body table th, .markdown-body table td { border-color: #30363d !important; } .markdown-body img { background: #0d1117; } .markdown-body blockquote { border-left-color: #8b949e; } .markdown-body hr { border-color: #30363d; } '; document.head.appendChild(style); })(); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Highlight search terms from Google/DuckDuckGo/Bing referrer (function() { var ref = document.referrer; var terms = []; if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) { var url = new URL(ref); var q = url.searchParams.get('q') || url.searchParams.get('p'); if (q) { terms = q.split(/\s+/).filter(function(t) { return t.length > 2; }); } } if (terms.length === 0) return; var style = document.createElement('style'); style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }'; document.head.appendChild(style); function highlight(node) { if (node.nodeType === 3) { // text node var text = node.textContent; var found = false; terms.forEach(function(term) { var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ' chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman
, 'i'); if (__m === '*' || __re.test(location.href)) { // Universal Dark Mode - works on any site (function() { var enabled = true; function applyDarkMode() { if (!enabled) return; // Create style element if it doesn't exist var style = document.getElementById('universal-dark-mode-style'); if (!style) { style = document.createElement('style'); style.id = 'universal-dark-mode-style'; document.head.appendChild(style); } // Dark mode CSS - inverts colors but preserves images/video style.textContent = ' /* Invert everything except media */ html { filter: invert(1) hue-rotate(180deg) !important; background: #1a1a2e !important; } /* Restore images, videos, iframes, canvas */ img, video, iframe, canvas, svg, picture, [style*="background-image"] { filter: invert(1) hue-rotate(180deg) !important; } /* Preserve specific elements that should not be inverted */ .no-dark-mode, .no-dark-mode *, [data-theme="light"], [data-theme="light"], .ace_editor, .ace_editor *, .CodeMirror, .CodeMirror *, .monaco-editor, .monaco-editor *, .markdown-body pre, .markdown-body pre *, .highlight, .highlight *, pre code, pre code * { filter: none !important; } /* Fix common UI elements */ .modal, .popup, .dropdown-menu, .tooltip, .popover { filter: invert(1) hue-rotate(180deg) !important; background: #2d2d44 !important; border-color: #444 !important; } /* Scrollbars */ ::-webkit-scrollbar { background: #1a1a2e !important; } ::-webkit-scrollbar-thumb { background: #444 !important; } ::-webkit-scrollbar-thumb:hover { background: #555 !important; } /* Selection */ ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; } ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; } '; } function removeDarkMode() { var style = document.getElementById('universal-dark-mode-style'); if (style) style.remove(); } // Toggle with Alt+Shift+D document.addEventListener('keydown', function(e) { if (e.altKey && e.shiftKey && e.key === 'D') { e.preventDefault(); enabled = !enabled; if (enabled) { applyDarkMode(); console.log('[Universal Dark Mode] Enabled'); } else { removeDarkMode(); console.log('[Universal Dark Mode] Disabled'); } } }); // Apply on load applyDarkMode(); // Re-apply on dynamic content var observer = new MutationObserver(function(mutations) { if (enabled && !document.getElementById('universal-dark-mode-style')) { applyDarkMode(); } }); observer.observe(document.head, { childList: true }); console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle'); })(); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })(); chore(docs): fix docs API handling duped methods with different langs by agg23 · Pull Request #34596 · microsoft/playwright · GitHub
Skip to content

chore(docs): fix docs API handling duped methods with different langs - #34596

Closed
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix
Closed

chore(docs): fix docs API handling duped methods with different langs#34596
Adam Gastineau (agg23) wants to merge 3 commits into
microsoft:mainfrom
agg23:api-parser-duplicate-methods-fix

Conversation

@agg23

@agg23Adam Gastineau (agg23) commented Feb 3, 2025

Copy link
Copy Markdown
Contributor

This allows docs to specify multiple instances of the same top level method for different languages, allowing for differing docs or arguments.

This docs construction fails on the ports:

## async method: BrowserType.connect* since: v1.8
* langs: js
- returns: <[Browser]>
String A
## async method: BrowserType.connect* since: v1.8
* langs: python, csharp, java
- returns: <[Browser]>
String B
### param: BrowserType.connect.wsEndpoint* since: v1.10
-`wsEndpoint` <[string]>

The only difference here is we want to have different docs for JS and the other languages. Parts of the API parsing code handle overloads correctly, some parts do not. This PR fixes one of them to make this use casefunctional.

Additionally, existing docs (Video.saveAs) contained a method definition with no provided languages, and an override with certain languages specified. This didn't resolve properly, only showing the "all language" definition.

## async method: Video.saveAs* since: v1.11
String A
## method: Video.saveAs* langs: java
* since: v1.11
String B
## async method: Video.saveAs* langs: python
* since: v1.11
String C

This situation now throws an error. The correct solution is to list each language under the corresponding docs entry.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

throw new Error(`Duplicate member ${clazz.name}.${name} for at least one language: ${member.langs.only}`);
} else {
// This member exists alongside the current one
clazz.membersArray.push(member);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, this will make two members with the same name, but different langs? Seems to differ from other places where we put lang-specific fields into the same member under .langs.

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already how the docs generation works (see https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md?plain=1#L1270-L1284, which generates two entries in api.json even before this change). I originally tested putting the member override into langs.overrides, but it didn't work as expected, and I didn't look into it further. It seems like langs.overrides is only used in very particular cases and probably doesn't like me doing things generally.

Comment threadutils/doclint/api_parser.js
existingMember.langs.types[lang] = returnType;
if (existingMember) {
if (isTypeOverride(existingMember, member) && (member.spec === undefined || member.spec.length === 0)) {
// Can only override return types if the overriding entry (`member`) has no spec content

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love comments!

@github-actions

Copy link
Copy Markdown
Contributor

Test results for "tests 1"

1 failed
❌ [webkit-page] › tests/page/page-leaks.spec.ts:82:5 › click should not leak @webkit-ubuntu-22.04-node18

15 flaky⚠️ [chromium-library] › tests/library/trace-viewer.spec.ts:1336:1 › should highlight locator in iframe while typing @chromium-ubuntu-22.04-node18
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-ct.spec.ts:59:5 › should run component tests after editing test @ubuntu-latest-node18-1
⚠️ [webkit-library] › tests/library/browsercontext-pages.spec.ts:105:3 › should return bounding box with page scale @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:87:5 › mobile viewport › should support window.orientation emulation @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsercontext-viewport-mobile.spec.ts:97:5 › mobile viewport › should fire orientationchange event @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/popup.spec.ts:115:3 › should inherit viewport size from browser context @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:31:3 › should use proxy Radoslav Kirilov (@smoke) @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:125:3 › should authenticate @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:44:14 › page screenshot › should work with a mobile viewport @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/screenshot.spec.ts:55:14 › page screenshot › should work with a mobile viewport and clip @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/video.spec.ts:441:5 › screencast › should work for popups @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-leaks.spec.ts:161:5 › waitFor should not leak @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-screenshot.spec.ts:868:5 › page screenshot animations › should wait for fonts to load @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37764 passed, 655 skipped
✔️✔️✔️

Merge workflow run.

@agg23

Copy link
Copy Markdown
ContributorAuthor

We have decided that the complexity of modifying the docs code is too high, and thus this change is not worthwhile.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@agg23@dgozman