From e5a0f7d5a7506581fe932c7e9e95f834a2d80307 Mon Sep 17 00:00:00 2001 From: Paul Gschwendtner Date: Fri, 12 Jan 2018 18:40:09 +0100 Subject: [PATCH] docs: show inherited properties (#9299) * Fixes that properties from mixins (e.g color, disabled) are not showing up in the docs. * No longer runs Dgeni twice when executing the docs task. Fixes #5284 --- src/lib/core/common-behaviors/color.ts | 1 + .../core/common-behaviors/disable-ripple.ts | 1 + src/lib/core/common-behaviors/disabled.ts | 1 + src/lib/core/common-behaviors/tabindex.ts | 1 + tools/dgeni/index.ts | 12 ++++++- tools/dgeni/processors/categorizer.ts | 2 ++ .../processors/merge-inherited-properties.ts | 34 +++++++++++++++++++ tools/gulp/tasks/docs.ts | 2 +- 8 files changed, 52 insertions(+), 2 deletions(-) create mode 100644 tools/dgeni/processors/merge-inherited-properties.ts diff --git a/src/lib/core/common-behaviors/color.ts b/src/lib/core/common-behaviors/color.ts index c96f1d41d418..a9f0ee74b6dc 100644 --- a/src/lib/core/common-behaviors/color.ts +++ b/src/lib/core/common-behaviors/color.ts @@ -11,6 +11,7 @@ import {ElementRef} from '@angular/core'; /** @docs-private */ export interface CanColor { + /** Theme color palette for the component. */ color: ThemePalette; } diff --git a/src/lib/core/common-behaviors/disable-ripple.ts b/src/lib/core/common-behaviors/disable-ripple.ts index d264bd6a5398..ad5748b2615e 100644 --- a/src/lib/core/common-behaviors/disable-ripple.ts +++ b/src/lib/core/common-behaviors/disable-ripple.ts @@ -11,6 +11,7 @@ import {Constructor} from './constructor'; /** @docs-private */ export interface CanDisableRipple { + /** Whether ripples are disabled. */ disableRipple: boolean; } diff --git a/src/lib/core/common-behaviors/disabled.ts b/src/lib/core/common-behaviors/disabled.ts index 4853a54d9ea7..da042e2c270c 100644 --- a/src/lib/core/common-behaviors/disabled.ts +++ b/src/lib/core/common-behaviors/disabled.ts @@ -11,6 +11,7 @@ import {Constructor} from './constructor'; /** @docs-private */ export interface CanDisable { + /** Whether the component is disabled. */ disabled: boolean; } diff --git a/src/lib/core/common-behaviors/tabindex.ts b/src/lib/core/common-behaviors/tabindex.ts index 5ea836a1eba8..c5709beb4abe 100644 --- a/src/lib/core/common-behaviors/tabindex.ts +++ b/src/lib/core/common-behaviors/tabindex.ts @@ -11,6 +11,7 @@ import {CanDisable} from './disabled'; /** @docs-private */ export interface HasTabIndex { + /** Tabindex of the component. */ tabIndex: number; } diff --git a/tools/dgeni/index.ts b/tools/dgeni/index.ts index 66e47c634afa..74bda0a1c586 100644 --- a/tools/dgeni/index.ts +++ b/tools/dgeni/index.ts @@ -2,6 +2,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 {MergeInheritedProperties} from './processors/merge-inherited-properties'; import {ComponentGrouper} from './processors/component-grouper'; import {ReadTypeScriptModules} from 'dgeni-packages/typescript/processors/readTypeScriptModules'; import {TsParser} from 'dgeni-packages/typescript/services/TsParser'; @@ -51,6 +52,9 @@ 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 merges inherited properties of a class with the class doc. +apiDocsPackage.processor(new MergeInheritedProperties()); + // Processor that filters out symbols that should not be shown in the docs. apiDocsPackage.processor(new DocsPrivateFilter()); @@ -99,8 +103,14 @@ apiDocsPackage.config((readTypeScriptModules: ReadTypeScriptModules, tsParser: T typescriptPathMap[`@angular/cdk/${packageName}`] = [`./cdk/${packageName}/index.ts`]; }); - tsParser.options.baseUrl = sourceDir; + materialPackages.forEach(packageName => { + typescriptPathMap[`@angular/material/${packageName}`] = [`./lib/${packageName}/index.ts`]; + }); + + // Add proper path mappings to the TSParser service of Dgeni. This ensures that properties + // from mixins (e.g. color, disabled) are showing up properly in the docs. tsParser.options.paths = typescriptPathMap; + tsParser.options.baseUrl = sourceDir; // Entry points for docs generation. All publically exported symbols found through these // files will have docs generated. diff --git a/tools/dgeni/processors/categorizer.ts b/tools/dgeni/processors/categorizer.ts index 8c6faedb7bcc..e8c830865501 100644 --- a/tools/dgeni/processors/categorizer.ts +++ b/tools/dgeni/processors/categorizer.ts @@ -114,6 +114,8 @@ export class Categorizer implements Processor { private decoratePropertyDoc(propertyDoc: CategorizedPropertyMemberDoc) { decorateDeprecatedDoc(propertyDoc); + // TODO(devversion): detect inputs based on the `inputs` property in the component metadata. + propertyDoc.isDirectiveInput = isDirectiveInput(propertyDoc); propertyDoc.directiveInputAlias = getDirectiveInputAlias(propertyDoc); diff --git a/tools/dgeni/processors/merge-inherited-properties.ts b/tools/dgeni/processors/merge-inherited-properties.ts new file mode 100644 index 000000000000..6415ccade612 --- /dev/null +++ b/tools/dgeni/processors/merge-inherited-properties.ts @@ -0,0 +1,34 @@ +import {DocCollection, Processor} from 'dgeni'; +import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExportDoc'; +import {MemberDoc} from 'dgeni-packages/typescript/api-doc-types/MemberDoc'; + +/** + * Processor that merges inherited properties of a class with the class doc. This is necessary + * to properly show public properties from TypeScript mixin interfaces in the API. + */ +export class MergeInheritedProperties implements Processor { + name = 'merge-inherited-properties'; + $runBefore = ['categorizer']; + + $process(docs: DocCollection) { + return docs + .filter(doc => doc.docType === 'class') + .forEach(doc => this.addInhertiedProperties(doc)); + } + + private addInhertiedProperties(doc: ClassExportDoc) { + doc.implementsClauses.filter(clause => clause.doc).forEach(clause => { + clause.doc!.members.forEach(member => this.addMemberDocIfNotPresent(doc, member)); + }); + + doc.extendsClauses.filter(clause => clause.doc).forEach(clause => { + clause.doc!.members.forEach(member => this.addMemberDocIfNotPresent(doc, member)); + }); + } + + private addMemberDocIfNotPresent(destination: ClassExportDoc, memberDoc: MemberDoc) { + if (!destination.members.find(member => member.name === memberDoc.name)) { + destination.members.push(memberDoc); + } + } +} diff --git a/tools/gulp/tasks/docs.ts b/tools/gulp/tasks/docs.ts index c3b394625d80..9a356d387ab0 100644 --- a/tools/gulp/tasks/docs.ts +++ b/tools/gulp/tasks/docs.ts @@ -150,7 +150,7 @@ task('api-docs', () => { * Minifies all HTML files that have been generated. The HTML files for the * highlighted examples can be skipped, because it won't have any effect. */ -task('minify-html-files', ['api-docs'], () => { +task('minify-html-files', () => { return src('dist/docs/+(api|markdown)/**/*.html') .pipe(htmlmin(htmlMinifierOptions)) .pipe(dest('dist/docs'));