From fbe0fb297786729f47e8f5c0cb640ba2ea32dff8 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Fri, 2 Oct 2020 19:19:19 -0700 Subject: [PATCH] fix(api.json): do not copy documentation from base class members (#4048) --- utils/doclint/check_public_api/MDBuilder.js | 36 +++++++++++---------- utils/doclint/check_public_api/index.js | 2 +- utils/doclint/check_public_api/test/test.js | 2 +- utils/doclint/generateApiJson.js | 4 ++- utils/generate_types/index.js | 2 +- 5 files changed, 25 insertions(+), 21 deletions(-) diff --git a/utils/doclint/check_public_api/MDBuilder.js b/utils/doclint/check_public_api/MDBuilder.js index 3179dca194..050cdaf40f 100644 --- a/utils/doclint/check_public_api/MDBuilder.js +++ b/utils/doclint/check_public_api/MDBuilder.js @@ -322,9 +322,10 @@ class MDOutline { /** * @param {!Page} page * @param {!Array} sources + * @param {!boolean} copyDocsFromSuperClasses * @return {!Promise<{documentation: !Documentation, errors: !Array}>} */ -module.exports = async function(page, sources) { +module.exports = async function(page, sources, copyDocsFromSuperClasses) { const classes = []; const errors = []; for (const source of sources) { @@ -334,25 +335,26 @@ module.exports = async function(page, sources) { } 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. - for (const [name, clazz] of documentation.classes.entries()) { - clazz.validateOrder(errors, clazz); + if (!clazz.extends || clazz.extends === 'EventEmitter' || clazz.extends === 'Error') + continue; + 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') - continue; - const superClass = documentation.classes.get(clazz.extends); - if (!superClass) { - errors.push(`Undefined superclass: ${superClass} in ${name}`); - continue; + clazz.membersArray = [...clazz.membersArray, ...superClass.membersArray]; + clazz.index(); } - 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 }; }; diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index 371ee75230..614827bcea 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -29,7 +29,7 @@ const EXCLUDE_PROPERTIES = new Set([ * @return {!Promise>} */ 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 jsDocumentation = filterJSDocumentation(jsSources, jsResult.documentation); const mdDocumentation = mdResult.documentation; diff --git a/utils/doclint/check_public_api/test/test.js b/utils/doclint/check_public_api/test/test.js index 296b288d2f..db03c134e3 100644 --- a/utils/doclint/check_public_api/test/test.js +++ b/utils/doclint/check_public_api/test/test.js @@ -63,7 +63,7 @@ async function testMDBuilder(name) { it(name, async({page}) => { const dirPath = path.join(__dirname, name); 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()); }); } diff --git a/utils/doclint/generateApiJson.js b/utils/doclint/generateApiJson.js index 70a59ffc99..25b50b154c 100644 --- a/utils/doclint/generateApiJson.js +++ b/utils/doclint/generateApiJson.js @@ -24,7 +24,7 @@ const PROJECT_DIR = path.join(__dirname, '..', '..'); const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')); const browser = await playwright.chromium.launch(); const page = await browser.newPage(); - const { documentation } = await mdBuilder(page, [api]); + const { documentation } = await mdBuilder(page, [api], false); const result = serialize(documentation); console.log(JSON.stringify(result)); await browser.close(); @@ -39,6 +39,8 @@ function serialize(documentation) { function serializeClass(clazz) { const result = { name: clazz.name }; + if (clazz.extends) + result.extends = clazz.extends; result.members = {}; for (const member of clazz.membersArray) result.members[member.name] = serializeMember(member); diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index 665ffc5a8a..ec69b5cfa5 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -36,7 +36,7 @@ let documentation; const browser = await chromium.launch(); const page = await browser.newPage(); 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(); const sources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []); const {documentation: jsDocumentation} = await require('../doclint/check_public_api/JSBuilder').checkSources(sources);