From 599ae30313a3c9f746905f73d18430c96e0eace4 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Tue, 3 Jan 2023 14:03:38 -0800 Subject: [PATCH] chore: update .net generator with deprecated/discouraged (#19843) --- docs/src/api/class-route.md | 19 +---------- utils/doclint/dotnetXmlDocumentation.js | 2 +- utils/doclint/generateDotnetApi.js | 45 ++++++++++++++++++------- 3 files changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/src/api/class-route.md b/docs/src/api/class-route.md index f684e79436a23..9999aac531735 100644 --- a/docs/src/api/class-route.md +++ b/docs/src/api/class-route.md @@ -638,28 +638,11 @@ Optional response body as raw bytes. ### option: Route.fulfill.json * since: v1.29 -* langs: js, python +* langs: js, python, csharp - `json` <[Serializable]> JSON response. This method will set the content type to `application/json` if not set. -### option: Route.fulfill.json -* since: v1.29 -* langs: csharp -- `json` <[JsonElement]> - -JSON response. This method will set the content type to `application/json` if not set. - -**Usage** - -```csharp -await page.RouteAsync("https://dog.ceo/api/breeds/list/all", async route => -{ - var json = /* JsonElement with test payload */; - await route.FulfillAsync(new () { Json: json }); -}); -``` - ### option: Route.fulfill.path * since: v1.8 - `path` <[path]> diff --git a/utils/doclint/dotnetXmlDocumentation.js b/utils/doclint/dotnetXmlDocumentation.js index a6627a1722ec3..66fae02c12977 100644 --- a/utils/doclint/dotnetXmlDocumentation.js +++ b/utils/doclint/dotnetXmlDocumentation.js @@ -117,7 +117,7 @@ function _wrapAndEscape(node, maxColumns = 0) { }; - let text = node.text; + let text = (node.text || '').replace(/↵/g, ' '); text = text.replace(/\[([^\]]*)\]\((.*?)\)/g, (match, linkName, linkUrl) => { const isInternal = !linkUrl.startsWith('http://') && !linkUrl.startsWith('https://'); if (isInternal) diff --git a/utils/doclint/generateDotnetApi.js b/utils/doclint/generateDotnetApi.js index cc39a7cd9ff84..368740feb29b2 100644 --- a/utils/doclint/generateDotnetApi.js +++ b/utils/doclint/generateDotnetApi.js @@ -25,7 +25,6 @@ const fs = require('fs'); const { parseApi } = require('./api_parser'); const { Type } = require('./documentation'); const { EOL } = require('os'); -const { execSync } = require('child_process'); const maxDocumentationColumnWidth = 80; Error.stackTraceLimit = 100; @@ -91,10 +90,10 @@ classNameMap.set('Readable', 'Stream'); * * @param {string} kind * @param {string} name - * @param {Documentation.MarkdownNode[]} spec + * @param {Documentation.MarkdownNode[]|null} spec * @param {string[]} body * @param {string} folder - * @param {string} extendsName + * @param {string|null} extendsName */ function writeFile(kind, name, spec, body, folder, extendsName = null) { const out = []; @@ -144,10 +143,19 @@ function renderClass(clazz) { renderMember(member, clazz, {}, body); } + /** @type {Documentation.MarkdownNode[]} */ + const spec = []; + if (clazz.deprecated) + spec.push({ type: 'text', text: '**DEPRECATED** ' + clazz.deprecated }); + if (clazz.discouraged) + spec.push({ type: 'text', text: clazz.discouraged }); + if (clazz.spec) + spec.push(...clazz.spec); + writeFile( 'public partial interface', name, - clazz.spec, + spec, body, apiDir, clazz.extends ? `I${toTitleCase(clazz.extends)}` : null); @@ -278,7 +286,22 @@ function renderConstructors(name, type, out) { } /** - * + * @param {Documentation.Member} member + * @param {string[]} out + */ +function renderMemberDoc(member, out) { + /** @type {Documentation.MarkdownNode[]} */ + const nodes = []; + if (member.deprecated) + nodes.push({ type: 'text', text: '**DEPRECATED** ' + member.deprecated }); + if (member.discouraged) + nodes.push({ type: 'text', text: member.discouraged }); + if (member.spec) + nodes.push(...member.spec); + out.push(...XmlDoc.renderXmlDoc(nodes, maxDocumentationColumnWidth)); +} + +/** * @param {Documentation.Member} member * @param {Documentation.Class|Documentation.Type} parent * @param {{nojson?: boolean, trimRunAndPrefix?: boolean}} options @@ -296,8 +319,7 @@ function renderMember(member, parent, options, out) { if (!member.type) throw new Error(`No Event Type for ${name} in ${parent.name}`); out.push(''); - if (member.spec) - out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); + renderMemberDoc(member, out); if (member.deprecated) out.push(`[System.Obsolete]`); out.push(`event EventHandler<${type}> ${name};`); @@ -314,8 +336,7 @@ function renderMember(member, parent, options, out) { const { name, jsonName } = overload; let { type } = overload; out.push(''); - if (member.spec) - out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); + renderMemberDoc(member, out); if (!member.clazz) out.push(`${member.required ? '[Required]\n' : ''}[JsonPropertyName("${jsonName}")]`); if (member.deprecated) @@ -623,7 +644,7 @@ function renderMethod(member, parent, name, options, out) { if (!explodedArgs.length) { if (!options.nodocs) { - out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); + renderMemberDoc(member, out); paramDocs.forEach((value, i) => printArgDoc(i, value, out)); } if (member.deprecated) @@ -633,7 +654,7 @@ function renderMethod(member, parent, name, options, out) { let containsOptionalExplodedArgs = false; explodedArgs.forEach((explodedArg, argIndex) => { if (!options.nodocs) - out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); + renderMemberDoc(member, out); const overloadedArgs = []; for (let i = 0; i < args.length; i++) { const arg = args[i]; @@ -662,7 +683,7 @@ function renderMethod(member, parent, name, options, out) { if (containsOptionalExplodedArgs) { const filteredArgs = args.filter(x => x !== 'OPTIONAL_EXPLODED_ARG'); if (!options.nodocs) - out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); + renderMemberDoc(member, out); filteredArgs.forEach(arg => { if (arg === 'EXPLODED_ARG') throw new Error(`Unsupported required union arg combined an optional union inside ${member.name}`);