honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

build(aio): add content rule to prevent usageNotes in non-export API docs (#24000) 

This commit also factors out `API_CONTAINED_DOC_TYPES` to be used by
both `filterContainedDocs` and `addAllowedPropertiesRules`.

PR Close #24000
This commit is contained in:
Pete Bacon Darwin 2018-05-16 17:51:35 +01:00 committed by Miško Hevery
parent 293ec78069
commit 4168c946c6
1 changed files with 57 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
aio/tools/transforms/angular-api-package/index.js vendored
View File

@ -42,12 +42,19 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'module']);
})
/**
* These are the doc types that are contained within other docs
*/
.factory(function API_CONTAINED_DOC_TYPES() {
return ['member', 'function-overload', 'get-accessor-info', 'set-accessor-info', 'parameter'];
})
/**
* These are the doc types that are API docs, including ones that will be merged into container docs,
* such as members and overloads.
*/
.factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER) {
return API_DOC_TYPES_TO_RENDER.concat(['member', 'function-overload']);
.factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER, API_CONTAINED_DOC_TYPES) {
return API_DOC_TYPES_TO_RENDER.concat(API_CONTAINED_DOC_TYPES);
})
// Where do we get the source files?
@ -155,6 +162,16 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
});
})
.config(function(filterContainedDocs, API_CONTAINED_DOC_TYPES) {
filterContainedDocs.docTypes = API_CONTAINED_DOC_TYPES;
})
.config(function(checkContentRules, EXPORT_DOC_TYPES, API_CONTAINED_DOC_TYPES) {
addMinLengthRules(checkContentRules);
addHeadingRules(checkContentRules, EXPORT_DOC_TYPES);
addAllowedPropertiesRules(checkContentRules, API_CONTAINED_DOC_TYPES);
})
.config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {
const API_SEGMENT = 'api';
@ -188,3 +205,41 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
autoLinkCode.docTypes = API_DOC_TYPES;
autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
});
function addMinLengthRules(checkContentRules) {
const createMinLengthRule = require('./content-rules/minLength');
const paramRuleSet = checkContentRules.docTypeRules['parameter'] = checkContentRules.docTypeRules['parameter'] || {};
const paramRules = paramRuleSet['name'] = paramRuleSet['name'] || [];
paramRules.push(createMinLengthRule());
}
function addHeadingRules(checkContentRules, EXPORT_DOC_TYPES) {
const createNoMarkdownHeadingsRule = require('./content-rules/noMarkdownHeadings');
const noMarkdownHeadings = createNoMarkdownHeadingsRule();
const allowOnlyLevel3Headings = createNoMarkdownHeadingsRule(1, 2, '4,');
const DOC_TYPES_TO_CHECK = EXPORT_DOC_TYPES.concat(['member', 'overload-info']);
const PROPS_TO_CHECK = ['description', 'shortDescription'];
DOC_TYPES_TO_CHECK.forEach(docType => {
const ruleSet = checkContentRules.docTypeRules[docType] = checkContentRules.docTypeRules[docType] || {};
PROPS_TO_CHECK.forEach(prop => {
const rules = ruleSet[prop] = ruleSet[prop] || [];
rules.push(noMarkdownHeadings);
});
const rules = ruleSet['usageNotes'] = ruleSet['usageNotes'] || [];
rules.push(allowOnlyLevel3Headings);
});
}
function addAllowedPropertiesRules(checkContentRules, API_CONTAINED_DOC_TYPES) {
const PROPS_TO_DISALLOW = ['usageNotes'];
API_CONTAINED_DOC_TYPES.forEach(docType => {
const ruleSet = checkContentRules.docTypeRules[docType] = checkContentRules.docTypeRules[docType] || {};
PROPS_TO_DISALLOW.forEach(prop => {
const rules = ruleSet[prop] = ruleSet[prop] || [];
rules.push((doc, prop, value) => value && `Invalid property: "${prop}" is not allowed on "${doc.docType}" docs.`);
});
});
}