diff --git a/package.json b/package.json index a7a9ed56466d..36081975412a 100644 --- a/package.json +++ b/package.json @@ -64,7 +64,7 @@ "axe-webdriverjs": "^1.1.1", "chalk": "^1.1.3", "dgeni": "^0.4.9", - "dgeni-packages": "^0.24.1", + "dgeni-packages": "^0.24.3", "firebase": "^4.0.0", "firebase-admin": "^5.0.0", "firebase-tools": "^3.11.0", diff --git a/tools/dgeni/index.ts b/tools/dgeni/index.ts index 892ae2fb3d14..87f116237380 100644 --- a/tools/dgeni/index.ts +++ b/tools/dgeni/index.ts @@ -3,7 +3,6 @@ import {patchLogService} from './patch-log-service'; import {DocsPrivateFilter} from './processors/docs-private-filter'; import {Categorizer} from './processors/categorizer'; import {FilterDuplicateExports} from './processors/filter-duplicate-exports'; -import {FilterExportAliases} from './processors/filter-export-aliases'; import {MergeInheritedProperties} from './processors/merge-inherited-properties'; import {ComponentGrouper} from './processors/component-grouper'; import {ReadTypeScriptModules} from 'dgeni-packages/typescript/processors/readTypeScriptModules'; @@ -53,9 +52,6 @@ export const apiDocsPackage = new Package('material2-api-docs', [ // Processor that filters out duplicate exports that should not be shown in the docs. apiDocsPackage.processor(new FilterDuplicateExports()); -// Processor that filters out aliased exports that should not be shown in the docs. -apiDocsPackage.processor(new FilterExportAliases()); - // Processor that merges inherited properties of a class with the class doc. apiDocsPackage.processor(new MergeInheritedProperties()); diff --git a/tools/dgeni/processors/filter-duplicate-exports.ts b/tools/dgeni/processors/filter-duplicate-exports.ts index 8438e17b3b14..0bcdc451f0ea 100644 --- a/tools/dgeni/processors/filter-duplicate-exports.ts +++ b/tools/dgeni/processors/filter-duplicate-exports.ts @@ -7,36 +7,58 @@ import {ExportDoc} from 'dgeni-packages/typescript/api-doc-types/ExportDoc'; * * ```ts * // Some file in @angular/cdk/scrolling - * export {ScrollDispatcher} from './scroll-dispatcher.ts'; + * export {ScrollDispatcher} from './scroll-dispatcher'; * * // Other file in @angular/cdk/overlay * export {ScrollDispatcher} from '@angular/cdk/scrolling'; + * + * // Re-export of the same export with a different name (alias). + * export {ScrollDispatcher as X} from './scroll-dispatcher'; * ``` * - * This issue occurs sometimes in the Angular Material repository, if specific imports are - * re-exported from a different secondary entry-point (e.g. ScrollDispatcher in the overlay). + * This issue occurs sometimes in the Angular Material repository, because some imports are + * re-exported with a different name (for deprecation), or from a different secondary entry-point. */ export class FilterDuplicateExports implements Processor { name = 'filter-duplicate-exports'; - $runBefore = ['filter-export-aliases']; + $runBefore = ['categorizer']; $process(docs: DocCollection) { - return docs.forEach(this.checkForDuplicateExports); + const duplicateDocs = this.findDuplicateExports(docs); + return docs.filter(d => !duplicateDocs.has(d)); } - checkForDuplicateExports = (doc: ExportDoc, index: number, docs: DocCollection) => { - if (!(doc instanceof ExportDoc)) { - return; - } + findDuplicateExports(docs: DocCollection) { + const duplicates = new Set(); - // Checks for export documents that have the same name, originate from the same module, but - // have a different Dgeni document id. Those documents can be considered as duplicates. - const duplicateDocs = docs.filter(d => doc.name === d.name && - doc.originalModule === d.originalModule && doc.id !== d.id); + docs.forEach(doc => { + if (!(doc instanceof ExportDoc)) { + return; + } - if (duplicateDocs.length > 0) { - docs.splice(index, 1); - } - } + // Check for Dgeni documents that refer to the same TypeScript symbol. Those can be + // considered as duplicates of the current document. + const similarDocs = docs.filter(d => d.symbol === doc.symbol); + + if (similarDocs.length > 1) { + // If there are multiple docs that refer to the same TypeScript symbol, but have a + // different name than the resolved symbol, we can remove those documents, since they + // are just aliasing an already existing export. + similarDocs + .filter(d => d.symbol.name !== d.name) + .forEach(d => duplicates.add(d)); + const docsWithSameName = similarDocs + .filter(d => d.symbol.name === d.name); + + // If there are multiple docs that refer to the same TypeScript symbol and have + // the same name, we need to remove all of those duplicates except one. + if (docsWithSameName.length > 1) { + docsWithSameName.slice(1).forEach(d => duplicates.add(d)); + } + } + }); + + return duplicates; + } } diff --git a/tools/dgeni/processors/filter-export-aliases.ts b/tools/dgeni/processors/filter-export-aliases.ts deleted file mode 100644 index d4743df1bf0f..000000000000 --- a/tools/dgeni/processors/filter-export-aliases.ts +++ /dev/null @@ -1,31 +0,0 @@ -import {DocCollection, Processor} from 'dgeni'; - -/** - * 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 => { - // If the alias symbol and the actual resolved symbol have the same name, then this doc - // shouldn't be filtered. This check is necessary, because technically as per TypeScript, - // explicit and individual re-exports are being considered as aliases. - // For example: export {Test} from './my-file`; - return !(doc.aliasSymbol && doc.aliasSymbol.name !== doc.symbol.name); - }); - } -}