Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

chore: jsify dotnet generator (#6620)

Browse source
This commit is contained in:
Pavel Feldman 2021-05-17 19:16:14 -07:00 committed by GitHub
parent a728a89264
commit 691644666e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 270 additions and 299 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

569
utils/doclint/generateDotnetApi.js
View file

@ -27,248 +27,221 @@ const { EOL } = require('os');
const { execSync } = require('child_process'); const { execSync } = require('child_process');
const maxDocumentationColumnWidth = 80; const maxDocumentationColumnWidth = 80;
Error.stackTraceLimit = 100;
/** @type {Map<string, Documentation.Type>} */ /** @type {Map<string, Documentation.Type>} */
const additionalTypes = new Map(); // this will hold types that we discover, because of .NET specifics, like results const modelTypes = new Map(); // this will hold types that we discover, because of .NET specifics, like results
/** @type {Map<string, string>} */ /** @type {Map<string, string>} */
const documentedResults = new Map(); // will hold documentation for new types const documentedResults = new Map(); // will hold documentation for new types
/** @type {Map<string, string[]>} */ /** @type {Map<string, string[]>} */
const enumTypes = new Map(); const enumTypes = new Map();
/** @type {string[]} */
const nullableTypes = ['int', 'bool', 'decimal', 'float']; const nullableTypes = ['int', 'bool', 'decimal', 'float'];
let documentation;
/** @type {Map<string, string>} */
let classNameMap;
/** @type {Map<string, string>} */
const customTypeNames = new Map([ const customTypeNames = new Map([
['domcontentloaded', 'DOMContentLoaded'], ['domcontentloaded', 'DOMContentLoaded'],
['networkidle', 'NetworkIdle'], ['networkidle', 'NetworkIdle'],
['File', 'FilePayload'], ['File', 'FilePayload'],
]); ]);
{ const typesDir = process.argv[2] || path.join(__dirname, 'generate_types', 'csharp');
const typesDir = process.argv[2] || path.join(__dirname, 'generate_types', 'csharp'); const modelsDir = path.join(typesDir, "models");
let checkAndMakeDir = (path) => { const enumsDir = path.join(typesDir, "enums");
if (!fs.existsSync(path))
fs.mkdirSync(path, { recursive: true });
};
const modelsDir = path.join(typesDir, "models"); for (const dir of [typesDir, modelsDir, enumsDir])
const enumsDir = path.join(typesDir, "enums"); fs.mkdirSync(dir, { recursive: true });
checkAndMakeDir(typesDir); const documentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api'));
checkAndMakeDir(modelsDir); documentation.filterForLanguage('csharp');
checkAndMakeDir(enumsDir);
documentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api')); documentation.setLinkRenderer(item => {
documentation.filterForLanguage('csharp'); if (item.clazz)
return `<see cref="I${toTitleCase(item.clazz.name)}"/>`;
else if (item.member)
return `<see cref="I${toTitleCase(item.member.clazz.name)}.${toMemberName(item.member)}"/>`;
else if (item.option)
return `<paramref name="${item.option}"/>`;
else if (item.param)
return `<paramref name="${item.param}"/>`;
else
throw new Error('Unknown link format.');
});
documentation.setLinkRenderer(item => { // get the template for a class
if (item.clazz) const template = fs.readFileSync(path.join(__dirname, 'templates', 'interface.cs'), 'utf-8')
return `<see cref="${translateMemberName("interface", item.clazz.name, null)}"/>`; .replace('[PW_TOOL_VERSION]', `${__filename.substring(path.join(__dirname, '..', '..').length).split(path.sep).join(path.posix.sep)}`);
else if (item.member)
return `<see cref="${translateMemberName("interface", item.member.clazz.name, null)}.${translateMemberName(item.member.kind, item.member.name, item.member)}"/>`;
else if (item.option)
return `<paramref name="${item.option}"/>`;
else if (item.param)
return `<paramref name="${item.param}"/>`;
else
throw new Error('Unknown link format.');
});
// get the template for a class // we have some "predefined" types, like the mixed state enum, that we can map in advance
const template = fs.readFileSync(path.join(__dirname, 'templates', 'interface.cs'), 'utf-8') enumTypes.set("MixedState", ["On", "Off", "Mixed"]);
.replace('[PW_TOOL_VERSION]', `${__filename.substring(path.join(__dirname, '..', '..').length).split(path.sep).join(path.posix.sep)}`);
// we have some "predefined" types, like the mixed state enum, that we can map in advance // map the name to a C# friendly one (we prepend an I to denote an interface)
enumTypes.set("MixedState", ["On", "Off", "Mixed"]); const classNameMap = new Map(documentation.classesArray.map(x => [x.name, `I${toTitleCase(x.name)}`]));
// map the name to a C# friendly one (we prepend an I to denote an interface) // map some types that we know of
classNameMap = new Map(documentation.classesArray.map(x => [x.name, translateMemberName('interface', x.name, null)])); classNameMap.set('Error', 'Exception');
classNameMap.set('TimeoutError', 'TimeoutException');
classNameMap.set('EvaluationArgument', 'object');
classNameMap.set('boolean', 'bool');
classNameMap.set('Serializable', 'T');
classNameMap.set('any', 'object');
classNameMap.set('Buffer', 'byte[]');
classNameMap.set('path', 'string');
classNameMap.set('URL', 'string');
classNameMap.set('RegExp', 'Regex');
classNameMap.set('Readable', 'Stream');
// map some types that we know of /**
classNameMap.set('Error', 'Exception'); *
classNameMap.set('TimeoutError', 'TimeoutException'); * @param {string} kind
classNameMap.set('EvaluationArgument', 'object'); * @param {string} name
classNameMap.set('boolean', 'bool'); * @param {Documentation.MarkdownNode[]} spec
classNameMap.set('Serializable', 'T'); * @param {string[]} body
classNameMap.set('any', 'object'); * @param {string} folder
classNameMap.set('Buffer', 'byte[]'); * @param {string} extendsName
classNameMap.set('path', 'string'); */
classNameMap.set('URL', 'string'); function writeFile(kind, name, spec, body, folder, extendsName = null) {
classNameMap.set('RegExp', 'Regex'); const out = [];
classNameMap.set('Readable', 'Stream'); console.log(`Generating ${name}`);
// this are types that we don't explicility render even if we get the specs if (spec)
const ignoredTypes = ['TimeoutException']; out.push(...XmlDoc.renderXmlDoc(spec, maxDocumentationColumnWidth));
else {
let writeFile = (name, out, folder) => { let ownDocumentation = documentedResults.get(name);
let content = template.replace('[CONTENT]', out.join(`${EOL}\t`)); if (ownDocumentation) {
fs.writeFileSync(`${path.join(folder, name)}.generated.cs`, content); out.push('/// <summary>');
} out.push(`/// ${ownDocumentation}`);
out.push('/// </summary>');
/**
*
* @param {string} kind
* @param {string} name
* @param {Documentation.MarkdownNode[]} spec
* @param {function(string[]): void} callback
* @param {string} folder
* @param {string} extendsName
*/
let innerRenderElement = (kind, name, spec, callback, folder = typesDir, extendsName = null) => {
const out = [];
console.log(`Generating ${name}`);
if (spec)
out.push(...XmlDoc.renderXmlDoc(spec, maxDocumentationColumnWidth));
else {
let ownDocumentation = documentedResults.get(name);
if (ownDocumentation) {
out.push('/// <summary>');
out.push(`/// ${ownDocumentation}`);
out.push('/// </summary>');
}
} }
if (extendsName === 'IEventEmitter')
extendsName = null;
out.push(`public ${kind} ${name}${extendsName ? ` : ${extendsName}` : ''}`);
out.push('{');
callback(out);
// we want to separate the items with a space and this is nicer, than holding
// an index in each iterator down the line
const lastLine = out.pop();
if (lastLine !== '')
out.push(lastLine);
out.push('}');
writeFile(name, out, folder);
};
for (const element of documentation.classesArray) {
const name = classNameMap.get(element.name);
if (ignoredTypes.includes(name))
continue;
innerRenderElement('partial interface', name, element.spec, (out) => {
for (const member of element.membersArray) {
renderMember(member, element, out);
}
}, typesDir, translateMemberName('interface', element.extends, null));
} }
additionalTypes.forEach((type, name) => if (extendsName === 'IEventEmitter')
innerRenderElement('partial class', name, null, (out) => { extendsName = null;
// TODO: consider how this could be merged with the `translateType` check
if (type.union
&& type.union[0].name === 'null'
&& type.union.length == 2) {
type = type.union[1];
}
if (type.name === 'Array') { out.push(`public ${kind} ${name}${extendsName ? ` : ${extendsName}` : ''}`);
throw new Error('Array at this stage is unexpected.'); out.push('{');
} else if (type.properties) { out.push(...body);
for (const member of type.properties) { out.push('}');
let fakeType = new Type(name, null);
renderMember(member, fakeType, out);
}
} else {
console.log(type);
throw new Error(`Not sure what to do in this case.`);
}
}, modelsDir));
enumTypes.forEach((values, name) => let content = template.replace('[CONTENT]', out.join(EOL));
innerRenderElement('enum', name, null, (out) => { fs.writeFileSync(path.join(folder, name + '.generated.cs'), content);
out.push('\tUndefined = 0,'); }
values.forEach((v, i) => {
// strip out the quotes
v = v.replace(/[\"]/g, ``)
let escapedName = v.replace(/[-]/g, ' ')
.split(' ')
.map(word => customTypeNames.get(word) || word[0].toUpperCase() + word.substring(1)).join('');
out.push(`\t[EnumMember(Value = "${v}")]`); function renderClass(clazz) {
out.push(`\t${escapedName},`); const name = classNameMap.get(clazz.name);
}); if (name === 'TimeoutException')
}, enumsDir)); return;
if (process.argv[3] !== "--skip-format") { const body = [];
// run the formatting tool for .net, to ensure the files are prepped for (const member of clazz.membersArray)
execSync(`dotnet format -f "${typesDir}" --include-generated --fix-whitespace`); renderMember(member, clazz, body);
if (process.platform !== 'win32') {
for (const folder of [typesDir, path.join(typesDir, 'Models'), path.join(typesDir, 'Enums'), path.join(typesDir, 'Extensions'), path.join(typesDir, 'Constants')]) writeFile(
for (const name of fs.readdirSync(folder)) { 'partial interface',
if (!name.includes('\.cs')) name,
continue; clazz.spec,
const content = fs.readFileSync(path.join(folder, name), 'utf-8'); body,
fs.writeFileSync(path.join(folder, name), content.split('\r\n').join('\n')); typesDir,
} clazz.extends ? `I${toTitleCase(clazz.extends)}` : null);
}
/**
* @param {string} name
* @param {Documentation.Type} type
*/
function renderModelType(name, type) {
const body = [];
// TODO: consider how this could be merged with the `translateType` check
if (type.union
&& type.union[0].name === 'null'
&& type.union.length == 2) {
type = type.union[1];
}
if (type.name === 'Array') {
throw new Error('Array at this stage is unexpected.');
} else if (type.properties) {
for (const member of type.properties) {
let fakeType = new Type(name, null);
renderMember(member, fakeType, body);
}
} else {
console.log(type);
throw new Error(`Not sure what to do in this case.`);
}
writeFile('partial class', name, null, body, modelsDir);
}
/**
* @param {string} name
* @param {string[]} literals
*/
function renderEnum(name, literals) {
const body = [];
body.push('Undefined = 0,');
for (let literal of literals) {
// strip out the quotes
literal = literal.replace(/[\"]/g, ``)
let escapedName = literal.replace(/[-]/g, ' ')
.split(' ')
.map(word => customTypeNames.get(word) || word[0].toUpperCase() + word.substring(1)).join('');
body.push(`[EnumMember(Value = "${literal}")]`);
body.push(`${escapedName},`);
}
writeFile('enum', name, null, body, enumsDir);
}
for (const element of documentation.classesArray)
renderClass(element);
for (let [name, type] of modelTypes)
renderModelType(name, type);
for (let [name, literals] of enumTypes)
renderEnum(name, literals);
if (process.argv[3] !== "--skip-format") {
// run the formatting tool for .net, to ensure the files are prepped
execSync(`dotnet format -f "${typesDir}" --include-generated --fix-whitespace`);
if (process.platform !== 'win32') {
for (const folder of [typesDir, path.join(typesDir, 'Models'), path.join(typesDir, 'Enums'), path.join(typesDir, 'Extensions'), path.join(typesDir, 'Constants')])
for (const name of fs.readdirSync(folder)) {
if (!name.includes('\.cs'))
continue;
const content = fs.readFileSync(path.join(folder, name), 'utf-8');
fs.writeFileSync(path.join(folder, name), content.split('\r\n').join('\n'));
} }
} }
} }
/** /**
* @param {string} memberKind
* @param {string} name * @param {string} name
* @param {Documentation.Member} member
*/ */
function translateMemberName(memberKind, name, member = null) { function toArgumentName(name) {
if (!name) return name; return name === 'event' ? `@${name}` : name;
}
// we strip it for special chars, like @ because we might get called back with it in some special cases /**
// like, when generating classes inside methods for params * @param {Documentation.Member} member
name = name.replace(/[@-]/g, ''); * @param {{ omitAsync?: boolean; }=} options
*/
function toMemberName(member, options) {
const assumedName = toTitleCase(member.alias || member.name);
if (member.kind === 'interface')
return `I${assumedName}`;
const omitAsync = options && options.omitAsync;
if (!omitAsync && member.kind === 'method' && member.async && !assumedName.endsWith('Async'))
return `${assumedName}Async`;
return assumedName;
}
if (memberKind === 'argument') { /**
if (['params', 'event'].includes(name)) { // just in case we want to add others * @param {string} name
return `@${name}`; * @returns {string}
} else { */
return name; function toTitleCase(name) {
}
}
// check if there's an alias in the docs, in which case
// we return that, otherwise, we apply our dotnet magic to it
if (member) {
if (member.alias !== name) {
return member.alias;
}
}
// we sanitize some common abbreviations to ensure consistency
name = name.replace(/(HTTP[S]?)/g, (m, g) => { name = name.replace(/(HTTP[S]?)/g, (m, g) => {
return g[0].toUpperCase() + g.substring(1).toLowerCase(); return g[0].toUpperCase() + g.substring(1).toLowerCase();
}); });
return name.charAt(0).toUpperCase() + name.substring(1);
let assumedName = name.charAt(0).toUpperCase() + name.substring(1);
switch (memberKind) {
case "interface":
// apply name mapping if the map exists
let mappedName = classNameMap ? classNameMap.get(assumedName) : null;
if (mappedName)
return mappedName;
return `I${assumedName}`;
case "method":
if (member && member.async)
return `${assumedName}Async`;
return assumedName;
case "event":
return `${assumedName}`;
case "enum":
return `${assumedName}`;
default:
return `${assumedName}`;
}
} }
/** /**
@ -278,16 +251,9 @@ function translateMemberName(memberKind, name, member = null) {
* @param {string[]} out * @param {string[]} out
*/ */
function renderMember(member, parent, out) { function renderMember(member, parent, out) {
let output = line => { let name = toMemberName(member);
if (typeof (line) === 'string')
out.push(`\t${line}`);
else
out.push(...line.map(x => `\t${x}`));
}
let name = translateMemberName(member.kind, member.name, member);
if (member.kind === 'method') { if (member.kind === 'method') {
renderMethod(member, parent, output, name); renderMethod(member, parent, name, out);
} else { } else {
/** @type string */ /** @type string */
let type = translateType(member.type, parent, t => generateNameDefault(member, name, t, parent)); let type = translateType(member.type, parent, t => generateNameDefault(member, name, t, parent));
@ -295,16 +261,16 @@ function renderMember(member, parent, out) {
if (!member.type) if (!member.type)
throw new Error(`No Event Type for ${name} in ${parent.name}`); throw new Error(`No Event Type for ${name} in ${parent.name}`);
if (member.spec) if (member.spec)
output(XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth));
output(`event EventHandler<${type}> ${name};`); out.push(`event EventHandler<${type}> ${name};`);
} else if (member.kind === 'property') { } else if (member.kind === 'property') {
if (member.spec) if (member.spec)
output(XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth));
let propertyOrigin = member.name; let propertyOrigin = member.name;
if (member.type.expression === '[string]|[float]') if (member.type.expression === '[string]|[float]')
propertyOrigin = `${member.name}String`; propertyOrigin = `${member.name}String`;
if (!member.clazz) if (!member.clazz)
output(`[JsonPropertyName("${propertyOrigin}")]`) out.push(`[JsonPropertyName("${propertyOrigin}")]`)
if (parent && member && member.name === 'children') { // this is a special hack for Accessibility if (parent && member && member.name === 'children') { // this is a special hack for Accessibility
console.warn(`children property found in ${parent.name}, assuming array.`); console.warn(`children property found in ${parent.name}, assuming array.`);
type = `IEnumerable<${parent.name}>`; type = `IEnumerable<${parent.name}>`;
@ -313,15 +279,13 @@ function renderMember(member, parent, out) {
if (!type.endsWith('?') && !member.required && nullableTypes.includes(type)) if (!type.endsWith('?') && !member.required && nullableTypes.includes(type))
type = `${type}?`; type = `${type}?`;
if (member.clazz) if (member.clazz)
output(`public ${type} ${name} { get; }`); out.push(`public ${type} ${name} { get; }`);
else else
output(`public ${type} ${name} { get; set; }`); out.push(`public ${type} ${name} { get; set; }`);
} else { } else {
throw new Error(`Problem rendering a member: ${type} - ${name} (${member.kind})`); throw new Error(`Problem rendering a member: ${type} - ${name} (${member.kind})`);
} }
} }
// we're separating each entry and removing the final blank line when rendering
out.push(''); out.push('');
} }
@ -340,13 +304,13 @@ function generateNameDefault(member, name, t, parent) {
return 'object'; return 'object';
// we'd get this call for enums, primarily // we'd get this call for enums, primarily
let enumName = generateEnumNameIfApplicable(member, name, t, parent); let enumName = generateEnumNameIfApplicable(t);
if (!enumName && member) { if (!enumName && member) {
if (member.kind === 'method' || member.kind === 'property') { if (member.kind === 'method' || member.kind === 'property') {
let names = [ let names = [
parent.alias || parent.name, parent.alias || parent.name,
translateMemberName(``, member.alias || member.name, null), toTitleCase(member.alias || member.name),
translateMemberName(``, name, null), toTitleCase(name),
]; ];
if (names[2] === names[1]) if (names[2] === names[1])
names.pop(); // get rid of duplicates, cheaply names.pop(); // get rid of duplicates, cheaply
@ -363,7 +327,7 @@ function generateNameDefault(member, name, t, parent) {
attemptedName = attemptedName.substring(0, attemptedName.length - 1); attemptedName = attemptedName.substring(0, attemptedName.length - 1);
if (customTypeNames.get(attemptedName)) if (customTypeNames.get(attemptedName))
attemptedName = customTypeNames.get(attemptedName); attemptedName = customTypeNames.get(attemptedName);
let probableType = additionalTypes.get(attemptedName); let probableType = modelTypes.get(attemptedName);
if ((probableType && typesDiffer(t, probableType)) if ((probableType && typesDiffer(t, probableType))
|| (["Value"].includes(attemptedName))) { || (["Value"].includes(attemptedName))) {
if (!names.length) if (!names.length)
@ -371,7 +335,7 @@ function generateNameDefault(member, name, t, parent) {
attemptedName = `${names.pop()}${attemptedName}`; attemptedName = `${names.pop()}${attemptedName}`;
continue; continue;
} else { } else {
additionalTypes.set(attemptedName, t); modelTypes.set(attemptedName, t);
} }
break; break;
} }
@ -386,36 +350,44 @@ function generateNameDefault(member, name, t, parent) {
return enumName || t.name; return enumName || t.name;
} }
function generateEnumNameIfApplicable(member, name, type, parent) { /**
*
* @param {Documentation.Type} type
* @returns
*/
function generateEnumNameIfApplicable(type) {
if (!type.union) if (!type.union)
return null; return null;
const potentialValues = type.union.filter(u => u.name.startsWith('"')); const potentialValues = type.union.filter(u => u.name.startsWith('"'));
if ((potentialValues.length !== type.union.length) if ((potentialValues.length !== type.union.length)
&& !(type.union[0].name === 'null' && potentialValues.length === type.union.length - 1)) && !(type.union[0].name === 'null' && potentialValues.length === type.union.length - 1)) {
return null; // this isn't an enum, so we don't care, we let the caller generate the name return null; // this isn't an enum, so we don't care, we let the caller generate the name
}
if (type && type.name) return type.name;
return type.name;
// our enum naming policy leaves a few bits to be desired, but it'll do for now
// however, with the recent changes, this almost never gets called anymore
return translateMemberName('enum', name, type);
} }
/** /**
* Rendering a method is so _special_, with so many weird edge cases, that it * Rendering a method is so _special_, with so many weird edge cases, that it
* makes sense to put it separate from the other logic. * makes sense to put it separate from the other logic.
* @param {Documentation.Member} member * @param {Documentation.Member} member
* @param {Documentation.Class|Documentation.Type} parent * @param {Documentation.Class | Documentation.Type} parent
* @param {Function} output * @param {string} name
* @param {string[]} out
*/ */
function renderMethod(member, parent, output, name) { function renderMethod(member, parent, name, out) {
const typeResolve = (type) => translateType(type, parent, (t) => {
let newName = `${parent.name}${translateMemberName(member.kind, member.name, null)}Result`; /**
documentedResults.set(newName, `Result of calling <see cref="${translateMemberName("interface", parent.name)}.${translateMemberName(member.kind, member.name, member)}"/>.`); * @param {Documentation.Type} type
return newName; * @returns
}); */
function resolveType(type) {
return translateType(type, parent, (t) => {
let newName = `${parent.name}${toMemberName(member, { omitAsync: true })}Result`;
documentedResults.set(newName, `Result of calling <see cref="I${toTitleCase(parent.name)}.${toMemberName(member)}"/>.`);
return newName;
});
}
/** @type {Map<string, string[]>} */ /** @type {Map<string, string[]>} */
const paramDocs = new Map(); const paramDocs = new Map();
@ -445,16 +417,14 @@ function renderMethod(member, parent, output, name) {
type = `dynamic`; type = `dynamic`;
} else { } else {
type = classNameMap.get(innerType.name); type = classNameMap.get(innerType.name);
if (!type) { if (!type)
type = typeResolve(innerType); type = resolveType(innerType);
}
if (isArray) if (isArray)
type = `IReadOnlyCollection<${type}>`; type = `IReadOnlyCollection<${type}>`;
} }
} }
type = type || typeResolve(member.type); type = type || resolveType(member.type);
// TODO: this is something that will probably go into the docs // TODO: this is something that will probably go into the docs
// translate simple getters into read-only properties, and simple // translate simple getters into read-only properties, and simple
// set-only methods to settable properties // set-only methods to settable properties
@ -464,8 +434,8 @@ function renderMethod(member, parent, output, name) {
&& !name.startsWith('As')) { && !name.startsWith('As')) {
if (!member.async) { if (!member.async) {
if (member.spec) if (member.spec)
output(XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth));
output(`${type} ${name} { get; }`); out.push(`${type} ${name} { get; }`);
return; return;
} }
} }
@ -484,8 +454,11 @@ function renderMethod(member, parent, output, name) {
} }
// render args // render args
/** @type {string[]} */
let args = []; let args = [];
/** @type {string[]} */
let explodedArgs = []; let explodedArgs = [];
/** @type {Map<string, string>} */
let argTypeMap = new Map([]); let argTypeMap = new Map([]);
/** /**
* *
@ -494,7 +467,7 @@ function renderMethod(member, parent, output, name) {
* @param {Documentation.Member} argument * @param {Documentation.Member} argument
* @param {boolean} isExploded * @param {boolean} isExploded
*/ */
const pushArg = (innerArgType, innerArgName, argument, isExploded = false) => { function pushArg(innerArgType, innerArgName, argument, isExploded = false) {
let isNullable = nullableTypes.includes(innerArgType); let isNullable = nullableTypes.includes(innerArgType);
const requiredPrefix = (argument.required || isExploded) ? "" : isNullable ? "?" : ""; const requiredPrefix = (argument.required || isExploded) ? "" : isNullable ? "?" : "";
const requiredSuffix = (argument.required || isExploded) ? "" : " = default"; const requiredSuffix = (argument.required || isExploded) ? "" : " = default";
@ -504,17 +477,19 @@ function renderMethod(member, parent, output, name) {
else else
args.push(push); args.push(push);
argTypeMap.set(push, innerArgName); argTypeMap.set(push, innerArgName);
}; }
/**
let parseArg = (/** @type {Documentation.Member} */ arg) => { * @param {Documentation.Member} arg
*/
function processArg(arg) {
if (arg.name === "options") { if (arg.name === "options") {
arg.type.properties.forEach(parseArg); arg.type.properties.forEach(processArg);
return; return;
} }
if (arg.type.expression === '[string]|[path]') { if (arg.type.expression === '[string]|[path]') {
let argName = translateMemberName('argument', arg.name, null); let argName = toArgumentName(arg.name);
pushArg("string", `${argName} = null`, arg); pushArg("string", `${argName} = null`, arg);
pushArg("string", `${argName}Path = null`, arg); pushArg("string", `${argName}Path = null`, arg);
if (arg.spec) { if (arg.spec) {
@ -525,7 +500,7 @@ function renderMethod(member, parent, output, name) {
} else if (arg.type.expression === '[boolean]|[Array]<[string]>') { } else if (arg.type.expression === '[boolean]|[Array]<[string]>') {
// HACK: this hurts my brain too // HACK: this hurts my brain too
// we split this into two args, one boolean, with the logical name // we split this into two args, one boolean, with the logical name
let argName = translateMemberName('argument', arg.name, null); let argName = toArgumentName(arg.name);
let leftArgType = translateType(arg.type.union[0], parent, (t) => { throw new Error('Not supported'); }); let leftArgType = translateType(arg.type.union[0], parent, (t) => { throw new Error('Not supported'); });
let rightArgType = translateType(arg.type.union[1], parent, (t) => { throw new Error('Not supported'); }); let rightArgType = translateType(arg.type.union[1], parent, (t) => { throw new Error('Not supported'); });
@ -538,7 +513,7 @@ function renderMethod(member, parent, output, name) {
return; return;
} }
const argName = translateMemberName('argument', arg.alias || arg.name, null); const argName = toArgumentName(arg.alias || arg.name);
const argType = translateType(arg.type, parent, (t) => generateNameDefault(member, argName, t, parent)); const argType = translateType(arg.type, parent, (t) => generateNameDefault(member, argName, t, parent));
if (argType === null && arg.type.union) { if (argType === null && arg.type.union) {
@ -567,11 +542,11 @@ function renderMethod(member, parent, output, name) {
} }
pushArg(argType, argName, arg); pushArg(argType, argName, arg);
}; }
member.argsArray member.argsArray
.sort((a, b) => b.alias === 'options' ? -1 : 0) //move options to the back to the arguments list .sort((a, b) => b.alias === 'options' ? -1 : 0) //move options to the back to the arguments list
.forEach(parseArg); .forEach(processArg);
if (name.includes('WaitFor') && !['WaitForTimeoutAsync', 'WaitForFunctionAsync', 'WaitForLoadStateAsync', 'WaitForURLAsync', 'WaitForSelectorAsync', 'WaitForElementStateAsync'].includes(name)) { if (name.includes('WaitFor') && !['WaitForTimeoutAsync', 'WaitForFunctionAsync', 'WaitForLoadStateAsync', 'WaitForURLAsync', 'WaitForSelectorAsync', 'WaitForElementStateAsync'].includes(name)) {
const firstOptional = args.find(a => a.includes('=')); const firstOptional = args.find(a => a.includes('='));
@ -580,77 +555,59 @@ function renderMethod(member, parent, output, name) {
addParamsDoc('action', ['Action to perform while waiting']); addParamsDoc('action', ['Action to perform while waiting']);
} }
let printArgDoc = function (val, ind) {
if (val && val.length === 1) {
output(`/// <param name="${ind}">${val}</param>`);
} else {
output(`/// <param name="${ind}">`);
output(val.map(l => `/// ${l}`));
output(`/// </param>`);
}
}
let getArgType = function (argType) {
var type = argTypeMap.get(argType);
return type;
}
if (!explodedArgs.length) { if (!explodedArgs.length) {
output(XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth));
paramDocs.forEach((val, ind) => printArgDoc(val, ind)); paramDocs.forEach((value, i) => printArgDoc(i, value, out));
output(`${type} ${name}(${args.join(', ')});`); out.push(`${type} ${name}(${args.join(', ')});`);
} else { } else {
let containsOptionalExplodedArgs = false; let containsOptionalExplodedArgs = false;
explodedArgs.forEach((explodedArg, argIndex) => { explodedArgs.forEach((explodedArg, argIndex) => {
output(XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth));
let overloadedArgs = []; let overloadedArgs = [];
for (var i = 0; i < args.length; i++) { for (var i = 0; i < args.length; i++) {
let arg = args[i]; let arg = args[i];
if (arg === 'EXPLODED_ARG' || arg === 'OPTIONAL_EXPLODED_ARG') { if (arg === 'EXPLODED_ARG' || arg === 'OPTIONAL_EXPLODED_ARG') {
containsOptionalExplodedArgs = arg === 'OPTIONAL_EXPLODED_ARG'; containsOptionalExplodedArgs = arg === 'OPTIONAL_EXPLODED_ARG';
let argType = getArgType(explodedArg); let argType = argTypeMap.get(explodedArg);
printArgDoc(paramDocs.get(argType), argType); printArgDoc(argType, paramDocs.get(argType), out);
overloadedArgs.push(explodedArg); overloadedArgs.push(explodedArg);
} else { } else {
let argType = getArgType(arg); let argType = argTypeMap.get(arg);
printArgDoc(paramDocs.get(argType), argType); printArgDoc(argType, paramDocs.get(argType), out);
overloadedArgs.push(arg); overloadedArgs.push(arg);
} }
} }
output(`${type} ${name}(${overloadedArgs.join(', ')});`); out.push(`${type} ${name}(${overloadedArgs.join(', ')});`);
if (argIndex < explodedArgs.length - 1) if (argIndex < explodedArgs.length - 1)
output(``); // output a special blank line out.push(''); // output a special blank line
}); });
// If the exploded union arguments are optional, we also output a special // If the exploded union arguments are optional, we also output a special
// signature, to help prevent compilation errors with ambigious overloads. // signature, to help prevent compilation errors with ambiguous overloads.
// That particular overload only contains the required arguments, or rather // That particular overload only contains the required arguments, or rather
// contains all the arguments *except* the exploded ones. // contains all the arguments *except* the exploded ones.
if (containsOptionalExplodedArgs) { if (containsOptionalExplodedArgs) {
var filteredArgs = args.filter(x => x !== 'OPTIONAL_EXPLODED_ARG'); var filteredArgs = args.filter(x => x !== 'OPTIONAL_EXPLODED_ARG');
output(XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth)); out.push(...XmlDoc.renderXmlDoc(member.spec, maxDocumentationColumnWidth));
filteredArgs.forEach((arg) => { filteredArgs.forEach((arg) => {
if (arg === 'EXPLODED_ARG') if (arg === 'EXPLODED_ARG')
throw new Error(`Unsupported required union arg combined an optional union inside ${member.name}`); throw new Error(`Unsupported required union arg combined an optional union inside ${member.name}`);
let argType = getArgType(arg); let argType = argTypeMap.get(arg);
printArgDoc(paramDocs.get(argType), argType); printArgDoc(argType, paramDocs.get(argType), out);
}); });
output(`${type} ${name}(${filteredArgs.join(', ')});`); out.push(`${type} ${name}(${filteredArgs.join(', ')});`);
} }
} }
} }
/** /**
* *
* @callback generateNameCallback
* @param {Documentation.Type} t
* @returns {string}
*/
/**
* @param {Documentation.Type} type * @param {Documentation.Type} type
* @param {Documentation.Class|Documentation.Type} parent * @param {Documentation.Class|Documentation.Type} parent
* @param {generateNameCallback} generateNameCallback * @param {generateNameCallback} generateNameCallback
* @callback generateNameCallback
* @param {Documentation.Type} t
* @returns {string}
*/ */
function translateType(type, parent, generateNameCallback = t => t.name) { function translateType(type, parent, generateNameCallback = t => t.name) {
// a few special cases we can fix automatically // a few special cases we can fix automatically
@ -686,7 +643,7 @@ function translateType(type, parent, generateNameCallback = t => t.name) {
if (type.union.filter(u => u.name.startsWith(`"`)).length == type.union.length if (type.union.filter(u => u.name.startsWith(`"`)).length == type.union.length
|| isNullableEnum) { || isNullableEnum) {
// this is an enum // this is an enum
let enumName = generateNameCallback(type); let enumName = type.name;
if (!enumName) if (!enumName)
throw new Error(`This was supposed to be an enum, but it failed generating a name, ${type.name} ${parent ? parent.name : ""}.`); throw new Error(`This was supposed to be an enum, but it failed generating a name, ${type.name} ${parent ? parent.name : ""}.`);
@ -753,7 +710,7 @@ function translateType(type, parent, generateNameCallback = t => t.name) {
if (objectName === 'Object') { if (objectName === 'Object') {
throw new Error('Object unexpected'); throw new Error('Object unexpected');
} else if (type.name === 'Object') { } else if (type.name === 'Object') {
registerAdditionalType(objectName, type); registerModelType(objectName, type);
} }
return objectName; return objectName;
} }
@ -808,19 +765,33 @@ function translateType(type, parent, generateNameCallback = t => t.name) {
} }
/** /**
*
* @param {string} typeName * @param {string} typeName
* @param {Documentation.Type} type * @param {Documentation.Type} type
*/ */
function registerAdditionalType(typeName, type) { function registerModelType(typeName, type) {
if (['object', 'string', 'int'].includes(typeName)) if (['object', 'string', 'int'].includes(typeName))
return; return;
let potentialType = additionalTypes.get(typeName); let potentialType = modelTypes.get(typeName);
if (potentialType) { if (potentialType) {
console.log(`Type ${typeName} already exists, so skipping...`); console.log(`Type ${typeName} already exists, so skipping...`);
return; return;
} }
additionalTypes.set(typeName, type); modelTypes.set(typeName, type);
}
/**
* @param {string} name
* @param {string[]} value
* @param {string[]} out
*/
function printArgDoc(name, value, out) {
if (value.length === 1) {
out.push(`/// <param name="${name}">${value}</param>`);
} else {
out.push(`/// <param name="${name}">`);
out.push(...value.map(l => `/// ${l}`));
out.push(`/// </param>`);
}
} }