diff --git a/tools/dgeni/index.ts b/tools/dgeni/index.ts index 8688a1f1085..66e47c634af 100644 --- a/tools/dgeni/index.ts +++ b/tools/dgeni/index.ts @@ -1,6 +1,7 @@ import {Package} from 'dgeni'; import {DocsPrivateFilter} from './processors/docs-private-filter'; import {Categorizer} from './processors/categorizer'; +import {FilterExportAliases} from './processors/filter-export-aliases'; import {ComponentGrouper} from './processors/component-grouper'; import {ReadTypeScriptModules} from 'dgeni-packages/typescript/processors/readTypeScriptModules'; import {TsParser} from 'dgeni-packages/typescript/services/TsParser'; @@ -47,6 +48,8 @@ const materialPackages = globSync(path.join(sourceDir, 'lib', '*/')) export const apiDocsPackage = new Package('material2-api-docs', dgeniPackageDeps); +// Processor that filters out aliased exports that should not be shown in the docs. +apiDocsPackage.processor(new FilterExportAliases()); // Processor that filters out symbols that should not be shown in the docs. apiDocsPackage.processor(new DocsPrivateFilter()); diff --git a/tools/dgeni/processors/filter-export-aliases.ts b/tools/dgeni/processors/filter-export-aliases.ts new file mode 100644 index 00000000000..4b4529acda7 --- /dev/null +++ b/tools/dgeni/processors/filter-export-aliases.ts @@ -0,0 +1,48 @@ +import {DocCollection, Processor} from 'dgeni'; +import {ExportDoc} from 'dgeni-packages/typescript/api-doc-types/ExportDoc'; +import {ModuleDoc} from 'dgeni-packages/typescript/api-doc-types/ModuleDoc'; + +/** + * Processor to filter out Dgeni documents that are export aliases. Keeping them means + * that a given document shows up multiple times in the docs. + * + * ```ts + * export {ObserveContent} from './X'; + * export {ObserveContent as CdkObserveContent} from './X'; + * ``` + * + * This is a common pattern inside of Angular Material, but causes Dgeni to generate + * documents for both exports. The second document is identical to the original document and + * doesn't even show the aliased name. + * + * See: https://github.com/angular/dgeni-packages/issues/248 + */ +export class FilterExportAliases implements Processor { + name = 'filter-export-aliases'; + $runBefore = ['categorizer']; + + $process(docs: DocCollection) { + return docs.filter(doc => this.filterAliasExport(doc)); + } + + private filterAliasExport(doc: ExportDoc) { + if (!doc.moduleDoc) { + return true; + } + + const moduleDoc = doc.moduleDoc as ModuleDoc; + const duplicateDocs = moduleDoc.exports.filter(exportDoc => exportDoc.id === doc.id); + + // Remove the current export document if there are multiple Dgeni export documents with the + // same document id. If there are multiple docs with the same id, we can assume that this doc + // is an alias export. + if (duplicateDocs && duplicateDocs.length > 1) { + moduleDoc.exports.splice( + moduleDoc.exports.findIndex(exportDoc => exportDoc.id === doc.id), 1); + return false; + } + + return true; + } + +}