build(docs): ensure const types are not truncated (#13457)

* By default TypeScript truncates the types when calling `typeToString`. Since we don't want to truncate the types automatically, we need to work around: angular/dgeni-packages#276 until there is a possibility to change this using the `tsHost`.

Author: devversion

tools/dgeni/index.ts

@@ -11,6 +11,7 @@ import {ReadTypeScriptModules} from 'dgeni-packages/typescript/processors/readTy
 import {TsParser} from 'dgeni-packages/typescript/services/TsParser';
 import {sync as globSync} from 'glob';
 import * as path from 'path';
+import {NoTruncateConstTypeProcessor} from './processors/no-truncate-const-type';
 
 // Dgeni packages that the Material docs package depends on.
 const jsdocPackage = require('dgeni-packages/jsdoc');
@@ -51,6 +52,9 @@ export const apiDocsPackage = new Package('material2-api-docs', [
   typescriptPackage,
 ]);
 
+// Processor that ensures that Dgeni const docs don't truncate the resolved type string.
+apiDocsPackage.processor(new NoTruncateConstTypeProcessor());
+
 // Processor that filters out duplicate exports that should not be shown in the docs.
 apiDocsPackage.processor(new FilterDuplicateExports());
 

tools/dgeni/processors/no-truncate-const-type.ts

@@ -0,0 +1,41 @@
+import {DocCollection, Processor} from 'dgeni';
+import {Type, TypeChecker, TypeFormatFlags} from 'dgeni-packages/node_modules/typescript';
+import {ConstExportDoc} from 'dgeni-packages/typescript/api-doc-types/ConstExportDoc';
+
+/**
+ * Processor that works around a Dgeni TypeScript package issue where the type of a constant export
+ * is automatically truncated.
+ *
+ * Truncation of the type strings is causing unexpected results and also results in
+ * misleading documentation. See https://github.com/angular/dgeni-packages/issues/276
+ */
+export class NoTruncateConstTypeProcessor implements Processor {
+  name = 'no-truncate-const-type';
+  $runBefore = ['categorizer'];
+
+  $process(docs: DocCollection) {
+    return docs
+      .filter(doc => doc.docType === 'const')
+      .forEach(doc => doc.type && this.refreshResolvedTypeString(doc));
+  }
+
+  /** Refreshes the determined type string of the specified export const document. */
+  private refreshResolvedTypeString(doc: ConstExportDoc) {
+    const {variableDeclaration, typeChecker} = doc;
+
+    // Logic is aligned with the actual logic from the ConstExportDoc.
+    // dgeni-packages#typescript/src/api-doc-types/ConstExportDoc.ts#L22
+    if (variableDeclaration.type) {
+      doc.type = this.typeToString(
+          typeChecker, typeChecker.getTypeFromTypeNode(variableDeclaration.type));
+    } else if (variableDeclaration.initializer) {
+      doc.type = this.typeToString(
+          typeChecker, typeChecker.getTypeAtLocation(variableDeclaration.initializer));
+    }
+  }
+
+  /** Converts the specified type to a string that represents the type declaration. */
+  private typeToString(typeChecker: TypeChecker, type: Type): string {
+    return typeChecker.typeToString(type, undefined, TypeFormatFlags.NoTruncation);
+  }
+}