build(docs-infra): associate providedIn injectables with their NgModule (#41960)
Such injectables were not appearing in the providers lists of their NgModule. This commit updates the doc-gen to support associating these automatically. Further, it also allows developers to mark other injectables that are provided in an NgModule with a reference to the NgModule where they are provided. The commit also does a refactoring of the `processNgModuleDocs` dgeni processor code, to make it easier to maintain. Fixes #41203 PR Close #41960
This commit is contained in:
Pete Bacon Darwin
committed by
Alex Rickabaugh
Alex Rickabaugh
parent
23f6b76d1a
commit
85f5cb45d2
+196
-51
@@ -5,77 +5,222 @@ module.exports = function processNgModuleDocs(getDocFromAlias, createDocMessage,
|
||||
exportDocTypes: ['directive', 'pipe'],
|
||||
skipAbstractDirectives: true,
|
||||
$process(docs) {
|
||||
// Match all the directives/pipes to their module
|
||||
const errors = [];
|
||||
docs.forEach(doc => {
|
||||
|
||||
for (const doc of docs) {
|
||||
if (this.exportDocTypes.indexOf(doc.docType) !== -1) {
|
||||
const options = doc[`${doc.docType}Options`];
|
||||
|
||||
// Directives without a selector are considered abstract and do
|
||||
// not need to be part of any `@NgModule`.
|
||||
if (this.skipAbstractDirectives && doc.docType === 'directive' && !options.selector) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (!doc.ngModules || doc.ngModules.length === 0) {
|
||||
errors.push(createDocMessage(`"${doc.id}" has no @ngModule tag. Docs of type "${doc.docType}" must have this tag.`, doc));
|
||||
return;
|
||||
}
|
||||
|
||||
doc.ngModules.forEach((ngModule, index) => {
|
||||
|
||||
const ngModuleDocs = getDocFromAlias(ngModule, doc);
|
||||
|
||||
if (ngModuleDocs.length === 0) {
|
||||
errors.push(createDocMessage(`"@ngModule ${ngModule}" does not match a public NgModule`, doc));
|
||||
return;
|
||||
}
|
||||
|
||||
if (ngModuleDocs.length > 1) {
|
||||
errors.push(createDocMessage(`"@ngModule ${ngModule}" is ambiguous. Matches: ${ngModuleDocs.map(d => d.id).join(', ')}`, doc));
|
||||
return;
|
||||
}
|
||||
|
||||
const ngModuleDoc = ngModuleDocs[0];
|
||||
const containerName = getContainerName(doc.docType);
|
||||
const container = ngModuleDoc[containerName] = ngModuleDoc[containerName] || [];
|
||||
container.push(doc);
|
||||
|
||||
doc.ngModules[index] = ngModuleDoc;
|
||||
});
|
||||
// Match all the directives/pipes to their module
|
||||
this.processNgModuleExportDoc(doc, errors);
|
||||
}
|
||||
});
|
||||
|
||||
if (doc.docType === 'class') {
|
||||
this.processInjectableDoc(doc, errors);
|
||||
}
|
||||
}
|
||||
|
||||
if (errors.length) {
|
||||
errors.forEach(error => log.error(error));
|
||||
throw new Error('Failed to process NgModule relationships.');
|
||||
}
|
||||
|
||||
docs.forEach(doc => {
|
||||
// Update the NgModule docs after we have associated the directives/pipes/injectables docs.
|
||||
for (const doc of docs) {
|
||||
if (doc.docType === 'ngmodule') {
|
||||
Object.keys(doc.ngmoduleOptions).forEach(key => {
|
||||
const value = doc.ngmoduleOptions[key];
|
||||
if (value && !Array.isArray(value)) {
|
||||
doc.ngmoduleOptions[key] = [value];
|
||||
}
|
||||
});
|
||||
this.exportDocTypes.forEach(type => {
|
||||
const containerName = getContainerName(type);
|
||||
const container = doc[containerName];
|
||||
if (container) {
|
||||
container.sort(byId);
|
||||
}
|
||||
});
|
||||
convertAllPropertiesToArrays(doc.ngmoduleOptions);
|
||||
this.sortExportDocContainers(doc);
|
||||
this.processNgModuleProviders(doc);
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* Associate the `exportDoc` that is expected to have been exported from an `NgModule` with its
|
||||
* `NgModule` doc.
|
||||
*/
|
||||
processNgModuleExportDoc(exportDoc, errors) {
|
||||
const options = exportDoc[`${exportDoc.docType}Options`];
|
||||
|
||||
// Directives without a selector are considered abstract and do not need to be part of
|
||||
// any `@NgModule`.
|
||||
if (this.skipAbstractDirectives && exportDoc.docType === 'directive' && !options.selector) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (!exportDoc.ngModules || exportDoc.ngModules.length === 0) {
|
||||
errors.push(createDocMessage(
|
||||
`"${exportDoc.id}" has no @ngModule tag. Docs of type "${exportDoc.docType}" must have this tag.`,
|
||||
exportDoc));
|
||||
return;
|
||||
}
|
||||
|
||||
exportDoc.ngModules.forEach((ngModule, index) => {
|
||||
const ngModuleDoc = getNgModule(ngModule, exportDoc, errors);
|
||||
if (ngModuleDoc !== null) {
|
||||
const containerName = getContainerName(exportDoc.docType);
|
||||
const container = ngModuleDoc[containerName] = ngModuleDoc[containerName] || [];
|
||||
container.push(exportDoc);
|
||||
exportDoc.ngModules[index] = ngModuleDoc;
|
||||
}
|
||||
});
|
||||
},
|
||||
|
||||
/**
|
||||
* Associate the given `injectableDoc` with an NgModule doc if it is provided on an `NgModule`.
|
||||
*/
|
||||
processInjectableDoc(injectableDoc, errors) {
|
||||
const ngModules = [];
|
||||
|
||||
if (Array.isArray(injectableDoc.ngModules)) {
|
||||
for (const ngModule of injectableDoc.ngModules) {
|
||||
if (isWrappedInQuotes(ngModule)) {
|
||||
// `ngModule` is wrapped in quotes, so it will be one of `'any'`, `'root'` or `'platform'`
|
||||
// and is not associated with a specific NgModule. So just use the string.
|
||||
ngModules.push(ngModule.slice(1, -1));
|
||||
continue;
|
||||
}
|
||||
// Convert any `@ngModule` JSDOC tags to actual NgModule docs.
|
||||
// Don't add this doc to the NgModule doc, since this should already be in the `providers`
|
||||
// property of the `@NgModule()` decorator.
|
||||
const ngModuleDoc = getNgModule(ngModule, injectableDoc, errors);
|
||||
if (ngModuleDoc !== null) {
|
||||
ngModules.push(ngModuleDoc);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check for `providedIn` property on `@Injectable()`.
|
||||
for (const decorator of injectableDoc.decorators || []) {
|
||||
if (decorator.name === 'Injectable' && decorator.argumentInfo[0]) {
|
||||
const providedIn = decorator.argumentInfo[0].providedIn;
|
||||
this.processProvidedIn(providedIn, injectableDoc, ngModules, errors);
|
||||
}
|
||||
}
|
||||
|
||||
// Check for `providedIn` property on an `ɵprov` static property
|
||||
if (injectableDoc.symbol?.exports.has('ɵprov')) {
|
||||
const declaration = injectableDoc.symbol?.exports.get('ɵprov')?.valueDeclaration;
|
||||
const properties = declaration?.initializer?.arguments?.[0]?.properties;
|
||||
const providedInProp = properties?.find(prop => prop.name.text === 'providedIn');
|
||||
const providedInNode = providedInProp?.initializer;
|
||||
if (providedInNode) {
|
||||
const providedIn = providedInNode.getSourceFile().text.slice(providedInNode.pos, providedInNode.end).trim();
|
||||
this.processProvidedIn(providedIn, injectableDoc, ngModules, errors);
|
||||
}
|
||||
}
|
||||
|
||||
if (ngModules.length > 0) {
|
||||
injectableDoc.ngModules = ngModules;
|
||||
}
|
||||
},
|
||||
|
||||
processProvidedIn(providedIn, injectableDoc, ngModules, errors) {
|
||||
if (typeof providedIn !== 'string') {
|
||||
// `providedIn` is not a string, which means that this is not a tree-shakable provider
|
||||
// that needs associating with an NgModule.
|
||||
return;
|
||||
}
|
||||
if (isWrappedInQuotes(providedIn)) {
|
||||
// `providedIn` is wrapped in quotes, so it will be one of `'root'` or `'platform'` and
|
||||
// is not associated with a specific NgModule. So just use the string.
|
||||
ngModules.push(providedIn.slice(1, -1));
|
||||
return;
|
||||
}
|
||||
|
||||
// `providedIn` ought to reference a public NgModule
|
||||
const ngModuleDoc = getNgModule(providedIn, injectableDoc, errors);
|
||||
if (ngModuleDoc === null) {
|
||||
return;
|
||||
}
|
||||
|
||||
const container = ngModuleDoc.providers = ngModuleDoc.providers || [];
|
||||
container.push(injectableDoc);
|
||||
ngModules.push(ngModuleDoc);
|
||||
},
|
||||
|
||||
/**
|
||||
* Ensure that the arrays containing the docs exported from the `ngModuleDoc` are sorted.
|
||||
*/
|
||||
sortExportDocContainers(ngModuleDoc) {
|
||||
for (const type of this.exportDocTypes) {
|
||||
const container = ngModuleDoc[getContainerName(type)];
|
||||
if (Array.isArray(container)) {
|
||||
container.sort(byId);
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* Process the providers of the `ngModuleDoc`.
|
||||
*
|
||||
* Some providers come from the `@NgModule({providers: ...})` decoration.
|
||||
* Other providers come from the `@Injectable({providedIn: ...})` decoration.
|
||||
*/
|
||||
processNgModuleProviders(ngModuleDoc) {
|
||||
// Add providers from the NgModule decorator.
|
||||
const providers = ngModuleDoc.ngmoduleOptions.providers || [];
|
||||
// And also add those associated via the `Injectable` `providedIn` property.
|
||||
if (Array.isArray(ngModuleDoc.providers)) {
|
||||
for (const provider of ngModuleDoc.providers) {
|
||||
providers.push(`{ provide: ${provider.name}, useClass: ${provider.name} }`);
|
||||
}
|
||||
}
|
||||
|
||||
if (providers.length > 0) {
|
||||
ngModuleDoc.providers = providers;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
function getNgModule(ngModuleId, doc, errors) {
|
||||
const ngModuleDocs = getDocFromAlias(ngModuleId, doc);
|
||||
|
||||
if (ngModuleDocs.length === 0) {
|
||||
errors.push(
|
||||
createDocMessage(`The referenced "${ngModuleId}" does not match a public NgModule`, doc));
|
||||
return null;
|
||||
}
|
||||
|
||||
if (ngModuleDocs.length > 1) {
|
||||
errors.push(createDocMessage(
|
||||
`The referenced "${ngModuleId}" is ambiguous. Matches: ${ngModuleDocs.map(d => d.id).join(', ')}`,
|
||||
doc));
|
||||
return null;
|
||||
}
|
||||
|
||||
return ngModuleDocs[0];
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Compute the name of the array that will hold items of this type in the NgModule document.
|
||||
*/
|
||||
function getContainerName(docType) {
|
||||
return docType + 's';
|
||||
}
|
||||
|
||||
/**
|
||||
* Comparison function for sorting docs associated with an NgModule.
|
||||
*
|
||||
* This is used to sort docs by their id.
|
||||
*/
|
||||
function byId(a, b) {
|
||||
return a.id > b.id ? 1 : -1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert all the values of properties on the `obj` to arrays, if not already.
|
||||
*/
|
||||
function convertAllPropertiesToArrays(obj) {
|
||||
for (const [key, value] of Object.entries(obj)) {
|
||||
if (value && !Array.isArray(value)) {
|
||||
obj[key] = [value];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true if the `str` is wrapped in single or double quotes.
|
||||
*/
|
||||
function isWrappedInQuotes(str) {
|
||||
return /^['"].+['"]$/.test(str);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user