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

Author: devversion

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;
 }
 

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;
 }
 

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;
 }
 

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;
 }
 

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.

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);
 

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);
+    }
+  }
+}

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'));