Skip to content

Commit

Permalink
cherry-pick(#18818): chore: multiply overloaded options in csharp
Browse files Browse the repository at this point in the history
This way we'll get the same treatment in docs generator as well as
dotnet api generator.

This also adds non-suffixed aliases for string options, e.g. `Name` in
addition to `NameString` and `NameRegex`.

Fixes #18407.
  • Loading branch information
dgozman authored and aslushnikov committed Nov 16, 2022
1 parent c3335e4 commit 8f9bf0f
Show file tree
Hide file tree
Showing 4 changed files with 134 additions and 80 deletions.
16 changes: 16 additions & 0 deletions docs/src/api/class-route.md
Expand Up @@ -112,10 +112,18 @@ If set changes the request method (e.g. GET or POST)

### option: Route.continue.postData
* since: v1.8
* langs: js, python, java
- `postData` <[string]|[Buffer]>

If set changes the post data of request

### option: Route.continue.postData
* since: v1.8
* langs: csharp
- `postData` <[Buffer]>

If set changes the post data of request

### option: Route.continue.headers
* since: v1.8
- `headers` <[Object]<[string], [string]>>
Expand Down Expand Up @@ -378,10 +386,18 @@ If set changes the request method (e.g. GET or POST)

### option: Route.fallback.postData
* since: v1.23
* langs: js, python, java
- `postData` <[string]|[Buffer]>

If set changes the post data of request

### option: Route.fallback.postData
* since: v1.23
* langs: csharp
- `postData` <[Buffer]>

If set changes the post data of request

### option: Route.fallback.headers
* since: v1.23
- `headers` <[Object]<[string], [string]>>
Expand Down
16 changes: 8 additions & 8 deletions docs/src/chrome-extensions-js-python.md
Expand Up @@ -103,8 +103,8 @@ First, add fixtures that will load the extension:

```ts
// fixtures.ts
import { test as base, expect, chromium, type BrowserContext } from "@playwright/test";
import path from "path";
import { test as base, expect, chromium, type BrowserContext } from '@playwright/test';
import path from 'path';

export const test = base.extend<{
context: BrowserContext;
Expand Down Expand Up @@ -185,16 +185,16 @@ def extension_id(context) -> Generator[str, None, None]:
Then use these fixtures in a test:

```ts
import { test, expect } from "./fixtures";
import { test, expect } from './fixtures';

test("example test", async ({ page }) => {
await page.goto("https://example.com");
await expect(page.locator("body")).toHaveText("Changed by my-extension");
test('example test', async ({ page }) => {
await page.goto('https://example.com');
await expect(page.locator('body')).toHaveText('Changed by my-extension');
});

test("popup page", async ({ page, extensionId }) => {
test('popup page', async ({ page, extensionId }) => {
await page.goto(`chrome-extension://${extensionId}/popup.html`);
await expect(page.locator("body")).toHaveText("my-extension popup");
await expect(page.locator('body')).toHaveText('my-extension popup');
});
```

Expand Down
110 changes: 99 additions & 11 deletions utils/doclint/documentation.js
Expand Up @@ -59,6 +59,12 @@ const md = require('../markdown');
* }} Metainfo
*/

/**
* @typedef {{
* csharpOptionOverloadsShortNotation?: boolean,
* }} LanguageOptions
*/

class Documentation {
/**
* @param {!Array<!Documentation.Class>} classesArray
Expand Down Expand Up @@ -104,13 +110,14 @@ class Documentation {

/**
* @param {string} lang
* @param {LanguageOptions=} options
*/
filterForLanguage(lang) {
filterForLanguage(lang, options = {}) {
const classesArray = [];
for (const clazz of this.classesArray) {
if (clazz.langs.only && !clazz.langs.only.includes(lang))
continue;
clazz.filterForLanguage(lang);
clazz.filterForLanguage(lang, options);
classesArray.push(clazz);
}
this.classesArray = classesArray;
Expand Down Expand Up @@ -259,13 +266,14 @@ Documentation.Class = class {

/**
* @param {string} lang
* @param {LanguageOptions=} options
*/
filterForLanguage(lang) {
filterForLanguage(lang, options = {}) {
const membersArray = [];
for (const member of this.membersArray) {
if (member.langs.only && !member.langs.only.includes(lang))
continue;
member.filterForLanguage(lang);
member.filterForLanguage(lang, options);
membersArray.push(member);
}
this.membersArray = membersArray;
Expand Down Expand Up @@ -406,31 +414,41 @@ Documentation.Member = class {
}
}

/**
/**
* @param {string} lang
* @param {LanguageOptions=} options
*/
filterForLanguage(lang) {
filterForLanguage(lang, options = {}) {
if (!this.type)
return;
if (this.langs.aliases && this.langs.aliases[lang])
this.alias = this.langs.aliases[lang];
if (this.langs.types && this.langs.types[lang])
this.type = this.langs.types[lang];
this.type.filterForLanguage(lang);
this.type.filterForLanguage(lang, options);
const argsArray = [];
for (const arg of this.argsArray) {
if (arg.langs.only && !arg.langs.only.includes(lang))
continue;
const overriddenArg = (arg.langs.overrides && arg.langs.overrides[lang]) || arg;
overriddenArg.filterForLanguage(lang);
overriddenArg.filterForLanguage(lang, options);
// @ts-ignore
if (overriddenArg.name === 'options' && !overriddenArg.type.properties.length)
continue;
// @ts-ignore
overriddenArg.type.filterForLanguage(lang);
overriddenArg.type.filterForLanguage(lang, options);
argsArray.push(overriddenArg);
}
this.argsArray = argsArray;

const optionsArg = this.argsArray.find(arg => arg.name === 'options');
if (lang === 'csharp' && optionsArg) {
try {
patchCSharpOptionOverloads(optionsArg, options);
} catch (e) {
throw new Error(`Error processing csharp options in ${this.clazz?.name}.${this.name}: ` + e.message);
}
}
}

filterOutExperimental() {
Expand Down Expand Up @@ -642,15 +660,16 @@ Documentation.Type = class {

/**
* @param {string} lang
* @param {LanguageOptions=} options
*/
filterForLanguage(lang) {
filterForLanguage(lang, options = {}) {
if (!this.properties)
return;
const properties = [];
for (const prop of this.properties) {
if (prop.langs.only && !prop.langs.only.includes(lang))
continue;
prop.filterForLanguage(lang);
prop.filterForLanguage(lang, options);
properties.push(prop);
}
this.properties = properties;
Expand Down Expand Up @@ -839,4 +858,73 @@ function generateSourceCodeComment(spec) {
return md.render(comments, 120);
}

/**
* @param {Documentation.Member} optionsArg
* @param {LanguageOptions=} options
*/
function patchCSharpOptionOverloads(optionsArg, options = {}) {
const props = optionsArg.type?.properties;
if (!props)
return;
const propsToDelete = new Set();
const propsToAdd = [];
for (const prop of props) {
const union = prop.type?.union;
if (!union)
continue;
const isEnum = union[0].name.startsWith('"');
const isNullable = union.length === 2 && union.some(type => type.name === 'null');
if (isEnum || isNullable)
continue;

const shortNotation = [];
propsToDelete.add(prop);
for (const type of union) {
const suffix = csharpOptionOverloadSuffix(prop.name, type.name);
if (options.csharpOptionOverloadsShortNotation) {
if (type.name === 'string')
shortNotation.push(prop.alias);
else
shortNotation.push(prop.alias + suffix);
continue;
}

const newProp = prop.clone();
newProp.name = prop.name + suffix;
newProp.alias = prop.alias + suffix;
newProp.type = type;
propsToAdd.push(newProp);

if (type.name === 'string') {
const stringProp = prop.clone();
stringProp.type = type;
propsToAdd.push(stringProp);
}
}
if (options.csharpOptionOverloadsShortNotation) {
const newProp = prop.clone();
newProp.alias = newProp.name = shortNotation.join('|');
propsToAdd.push(newProp);
}
}
for (const prop of propsToDelete)
props.splice(props.indexOf(prop), 1);
props.push(...propsToAdd);
}

/**
* @param {string} option
* @param {string} type
*/
function csharpOptionOverloadSuffix(option, type) {
switch (type) {
case 'string': return 'String';
case 'RegExp': return 'Regex';
case 'function': return 'Func';
case 'Buffer': return 'Byte';
case 'Serializable': return 'Object';
}
throw new Error(`CSharp option "${option}" has unsupported type overload "${type}"`);
}

module.exports = Documentation;

0 comments on commit 8f9bf0f

Please sign in to comment.