yujunjun/playwright
1
0
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2025-06-26 21:40:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(api.json): do not copy documentation from base class members (#4048)

Browse Source
This commit is contained in:
Yury Semikhatsky 2020-10-02 19:19:19 -07:00 committed by GitHub
parent e214f795e0
commit fbe0fb2977
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 25 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
utils/doclint/check_public_api/MDBuilder.js
View File

@ -322,9 +322,10 @@ class MDOutline {
/** /**
* @param {!Page} page * @param {!Page} page
* @param {!Array<!Source>} sources * @param {!Array<!Source>} sources
* @param {!boolean} copyDocsFromSuperClasses
* @return {!Promise<{documentation: !Documentation, errors: !Array<string>}>} * @return {!Promise<{documentation: !Documentation, errors: !Array<string>}>}
*/ */
module.exports = async function(page, sources) { module.exports = async function(page, sources, copyDocsFromSuperClasses) {
const classes = []; const classes = [];
const errors = []; const errors = [];
for (const source of sources) { for (const source of sources) {
@ -334,25 +335,26 @@ module.exports = async function(page, sources) {
} }
const documentation = new Documentation(classes); const documentation = new Documentation(classes);
if (copyDocsFromSuperClasses) {
// Push base class documentation to derived classes.
for (const [name, clazz] of documentation.classes.entries()) {
clazz.validateOrder(errors, clazz);
// Push base class documentation to derived classes. if (!clazz.extends || clazz.extends === 'EventEmitter' || clazz.extends === 'Error')
for (const [name, clazz] of documentation.classes.entries()) { continue;
clazz.validateOrder(errors, clazz); const superClass = documentation.classes.get(clazz.extends);
if (!superClass) {
errors.push(`Undefined superclass: ${superClass} in ${name}`);
continue;
}
for (const memberName of clazz.members.keys()) {
if (superClass.members.has(memberName))
errors.push(`Member documentation overrides base: ${name}.${memberName} over ${clazz.extends}.${memberName}`);
}
if (!clazz.extends || clazz.extends === 'EventEmitter' || clazz.extends === 'Error') clazz.membersArray = [...clazz.membersArray, ...superClass.membersArray];
continue; clazz.index();
const superClass = documentation.classes.get(clazz.extends);
if (!superClass) {
errors.push(`Undefined superclass: ${superClass} in ${name}`);
continue;
} }
for (const memberName of clazz.members.keys()) {
if (superClass.members.has(memberName))
errors.push(`Member documentation overrides base: ${name}.${memberName} over ${clazz.extends}.${memberName}`);
}
clazz.membersArray = [...clazz.membersArray, ...superClass.membersArray];
clazz.index();
} }
return { documentation, errors }; return { documentation, errors };
}; };

2
utils/doclint/check_public_api/index.js
View File

@ -29,7 +29,7 @@ const EXCLUDE_PROPERTIES = new Set([
* @return {!Promise<!Array<!Message>>} * @return {!Promise<!Array<!Message>>}
*/ */
module.exports = async function lint(page, mdSources, jsSources) { module.exports = async function lint(page, mdSources, jsSources) {
const mdResult = await mdBuilder(page, mdSources); const mdResult = await mdBuilder(page, mdSources, true);
const jsResult = jsBuilder.checkSources(jsSources); const jsResult = jsBuilder.checkSources(jsSources);
const jsDocumentation = filterJSDocumentation(jsSources, jsResult.documentation); const jsDocumentation = filterJSDocumentation(jsSources, jsResult.documentation);
const mdDocumentation = mdResult.documentation; const mdDocumentation = mdResult.documentation;

2
utils/doclint/check_public_api/test/test.js
View File

@ -63,7 +63,7 @@ async function testMDBuilder(name) {
it(name, async({page}) => { it(name, async({page}) => {
const dirPath = path.join(__dirname, name); const dirPath = path.join(__dirname, name);
const sources = await Source.readdir(dirPath, '.md'); const sources = await Source.readdir(dirPath, '.md');
const {documentation} = await mdBuilder(page, sources); const {documentation} = await mdBuilder(page, sources, true);
expect(serialize(documentation)).toBe(fs.readFileSync(path.join(dirPath, 'result.txt')).toString()); expect(serialize(documentation)).toBe(fs.readFileSync(path.join(dirPath, 'result.txt')).toString());
}); });
} }

4
utils/doclint/generateApiJson.js
View File

@ -24,7 +24,7 @@ const PROJECT_DIR = path.join(__dirname, '..', '..');
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')); const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
const browser = await playwright.chromium.launch(); const browser = await playwright.chromium.launch();
const page = await browser.newPage(); const page = await browser.newPage();
const { documentation } = await mdBuilder(page, [api]); const { documentation } = await mdBuilder(page, [api], false);
const result = serialize(documentation); const result = serialize(documentation);
console.log(JSON.stringify(result)); console.log(JSON.stringify(result));
await browser.close(); await browser.close();
@ -39,6 +39,8 @@ function serialize(documentation) {
function serializeClass(clazz) { function serializeClass(clazz) {
const result = { name: clazz.name }; const result = { name: clazz.name };
if (clazz.extends)
result.extends = clazz.extends;
result.members = {}; result.members = {};
for (const member of clazz.membersArray) for (const member of clazz.membersArray)
result.members[member.name] = serializeMember(member); result.members[member.name] = serializeMember(member);

2
utils/generate_types/index.js
View File

@ -36,7 +36,7 @@ let documentation;
const browser = await chromium.launch(); const browser = await chromium.launch();
const page = await browser.newPage(); const page = await browser.newPage();
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')); const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
const {documentation: mdDocumentation} = await require('../doclint/check_public_api/MDBuilder')(page, [api]); const {documentation: mdDocumentation} = await require('../doclint/check_public_api/MDBuilder')(page, [api], true);
await browser.close(); await browser.close();
const sources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []); const sources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []);
const {documentation: jsDocumentation} = await require('../doclint/check_public_api/JSBuilder').checkSources(sources); const {documentation: jsDocumentation} = await require('../doclint/check_public_api/JSBuilder').checkSources(sources);