feat(typescript): add option to disable leading comment concatenation

Introduces a new option that allows developers to configure the `tsHost` to not concatenate multiple leading comments for a `TypeScript` node content.

The `tsHost` is a newly created service that delegates (for now) to the `tsParser` package for retrieving the content of a given node. The advantage of the `tsHost` is that people can inject the `tsHost` in Dgeni `.config()` and specify options or overwrite methods.

Related angular/components#12736.

Author: devversion

typescript/mocks/tsParser/multipleLeadingComments.ts

@@ -0,0 +1,10 @@
+/**
+ * Not a license comment.
+ */
+
+/**
+ * This is a test function
+ */
+export function test(a: string) {
+  return a;
+}

typescript/src/api-doc-types/AccessorInfoDoc.ts

@@ -1,4 +1,5 @@
 import { Declaration } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { MethodMemberDoc } from './MethodMemberDoc';
 import { PropertyMemberDoc } from './PropertyMemberDoc';
 
@@ -13,7 +14,10 @@ export class AccessorInfoDoc extends MethodMemberDoc {
   aliases = this.propertyDoc.aliases.map(alias => `${alias}:${this.accessorType}`);
   anchor = this.name;
 
-  constructor(public accessorType: 'get'|'set', public propertyDoc: PropertyMemberDoc, declaration: Declaration) {
-    super(propertyDoc.containerDoc, propertyDoc.symbol, declaration);
+  constructor(host: Host,
+              public accessorType: 'get'|'set',
+              public propertyDoc: PropertyMemberDoc,
+              declaration: Declaration) {
+    super(host, propertyDoc.containerDoc, propertyDoc.symbol, declaration);
   }
 }

typescript/src/api-doc-types/ApiDoc.ts

@@ -1,4 +1,5 @@
 import { Declaration, Symbol, TypeChecker } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { FileInfo } from '../services/TsParser/FileInfo';
 import { getContent } from '../services/TsParser/getContent';
 import { ModuleDoc } from './ModuleDoc';
@@ -31,16 +32,18 @@ export abstract class BaseApiDoc implements ApiDoc {
   startingLine = this.fileInfo.location.start.line +
     (this.fileInfo.location.start.character ? 1 : 0);
   endingLine = this.fileInfo.location.end.line;
-  content = getContent(this.declaration);
+  content = this.host.getContent(this.declaration);
   path: string = '';
   outputPath: string = '';
 
   originalModule = this.fileInfo.projectRelativePath
     .replace(new RegExp("\." + this.fileInfo.extension + "$"), "");
   typeChecker: TypeChecker = this.moduleDoc.typeChecker;
 
-  constructor(public moduleDoc: ModuleDoc,
+  constructor(public host: Host,
+              public moduleDoc: ModuleDoc,
               public symbol: Symbol,
               public declaration: Declaration,
-              public aliasSymbol?: Symbol) {}
+              public aliasSymbol?: Symbol) {
+  }
 }

typescript/src/api-doc-types/ClassExportDoc.ts

@@ -4,6 +4,7 @@ import { ClassLikeExportDoc } from '../api-doc-types/ClassLikeExportDoc';
 import { MemberDoc } from '../api-doc-types/MemberDoc';
 import { MethodMemberDoc } from '../api-doc-types/MethodMemberDoc';
 import { ModuleDoc } from '../api-doc-types/ModuleDoc';
+import { Host } from '../services/ts-host/host';
 
 /**
  * Classes are Class-like but also can contain static members
@@ -15,11 +16,12 @@ export class ClassExportDoc extends ClassLikeExportDoc {
   statics: MemberDoc[] = [];
   isAbstract = this.declaration.modifiers && this.declaration.modifiers.some(modifier => modifier.kind === SyntaxKind.AbstractKeyword);
 
-  constructor(
-    moduleDoc: ModuleDoc,
-    symbol: Symbol,
-    aliasSymbol?: Symbol) {
-    super(moduleDoc, symbol, symbol.valueDeclaration!, aliasSymbol);
+  constructor(host: Host,
+              moduleDoc: ModuleDoc,
+              symbol: Symbol,
+              aliasSymbol?: Symbol) {
+    super(host, moduleDoc, symbol, symbol.valueDeclaration!, aliasSymbol);
+
     if (symbol.exports) {
       this.statics = this.getMemberDocs(symbol.exports, moduleDoc.hidePrivateMembers);
     }
@@ -41,10 +43,10 @@ export class ClassExportDoc extends ClassLikeExportDoc {
     constructorSymbol.getDeclarations()!.forEach(declaration => {
       if ((declaration as FunctionLikeDeclaration).body) {
         // This is the "real" declaration of the method
-        constructorDoc = new MethodMemberDoc(this, constructorSymbol, declaration, overloads);
+        constructorDoc = new MethodMemberDoc(this.host, this, constructorSymbol, declaration, overloads);
       } else {
         // This is an overload signature of the method
-        overloads.push(new MethodMemberDoc(this, constructorSymbol, declaration, overloads));
+        overloads.push(new MethodMemberDoc(this.host, this, constructorSymbol, declaration, overloads));
       }
     });
     return constructorDoc || overloads.shift();

typescript/src/api-doc-types/ClassLikeExportDoc.ts

@@ -1,6 +1,15 @@
 /* tslint:disable:no-bitwise */
 /* tslint:disable:max-classes-per-file */
-import { Declaration, ExpressionWithTypeArguments, HeritageClause, Symbol, SymbolFlags, SyntaxKind, symbolName } from 'typescript';
+import {
+  Declaration,
+  ExpressionWithTypeArguments,
+  HeritageClause,
+  Symbol,
+  SymbolFlags,
+  symbolName,
+  SyntaxKind,
+} from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { getDecorators, ParsedDecorator } from "../services/TsParser/getDecorators";
 import { getTypeText } from '../services/TsParser/getTypeText';
 
@@ -23,15 +32,15 @@ export abstract class ClassLikeExportDoc extends ContainerExportDoc {
   descendants: ClassLikeExportDoc[] = [];
   typeParams = this.computeTypeParams();
 
-  constructor(
-      moduleDoc: ModuleDoc,
-      symbol: Symbol,
-      declaration: Declaration,
-      aliasSymbol?: Symbol) {
-        super(moduleDoc, symbol, declaration, aliasSymbol);
-        this.computeHeritageClauses();
-        this.addAliases();
-      }
+  constructor(host: Host, moduleDoc: ModuleDoc,
+              symbol: Symbol,
+              declaration: Declaration,
+              aliasSymbol?: Symbol) {
+    super(host, moduleDoc, symbol, declaration, aliasSymbol);
+
+    this.computeHeritageClauses();
+    this.addAliases();
+  }
 
   private computeTypeParams() {
     if (this.symbol.members) {

typescript/src/api-doc-types/ConstExportDoc.ts

@@ -1,5 +1,5 @@
-import { Symbol, Type, TypeFormatFlags, VariableDeclaration } from 'typescript';
-import { getDeclarationTypeText } from '../services/TsParser/getDeclarationTypeText';
+import { Symbol, VariableDeclaration } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { ExportDoc } from './ExportDoc';
 import { ModuleDoc } from './ModuleDoc';
 
@@ -8,8 +8,11 @@ export class ConstExportDoc extends ExportDoc {
   variableDeclaration = this.declaration as VariableDeclaration;
   type =  this.getTypeString();
 
-  constructor(moduleDoc: ModuleDoc, symbol: Symbol, aliasSymbol?: Symbol) {
-    super(moduleDoc, symbol, symbol.valueDeclaration!, aliasSymbol);
+  constructor(host: Host,
+              moduleDoc: ModuleDoc,
+              symbol: Symbol,
+              aliasSymbol?: Symbol) {
+    super(host, moduleDoc, symbol, symbol.valueDeclaration!, aliasSymbol);
   }
 
   private getTypeString() {

typescript/src/api-doc-types/ContainerExportDoc.ts

@@ -1,13 +1,12 @@
 /* tslint:disable:no-bitwise */
 import {
-    FunctionLikeDeclaration,
-    GetAccessorDeclaration,
-    Map,
-    SetAccessorDeclaration,
-    Symbol,
-    SymbolFlags,
-    SyntaxKind,
-    UnderscoreEscapedMap
+  FunctionLikeDeclaration,
+  GetAccessorDeclaration,
+  SetAccessorDeclaration,
+  Symbol,
+  SymbolFlags,
+  SyntaxKind,
+  UnderscoreEscapedMap,
 } from 'typescript';
 import { getAccessibility } from "../services/TsParser/getAccessibility";
 import { ExportDoc } from './ExportDoc';
@@ -56,21 +55,22 @@ export abstract class ContainerExportDoc extends ExportDoc {
             setAccessorDeclaration = declaration as SetAccessorDeclaration;
           } else if ((declaration as FunctionLikeDeclaration).body) {
             // This is the "real" declaration of the method
-            memberDoc = new MethodMemberDoc(this, member, declaration, overloads);
+            memberDoc = new MethodMemberDoc(this.host, this, member, declaration, overloads);
           } else {
             // This is an overload signature of the method
-            overloads.push(new MethodMemberDoc(this, member, declaration, overloads));
+            overloads.push(new MethodMemberDoc(this.host, this, member, declaration, overloads));
           }
         } else if (flags & PropertyMemberFlags) {
-          memberDoc = new PropertyMemberDoc(this, member, declaration, null, null);
+          memberDoc = new PropertyMemberDoc(this.host, this, member, declaration, null, null);
         } else {
           throw new Error(`Unknown member type for member ${member.name}`);
         }
       }
 
       // If at least one of the declarations was an accessor then the whole member is a property.
       if (getAccessorDeclaration || setAccessorDeclaration) {
-        memberDoc = new PropertyMemberDoc(this, member, null, getAccessorDeclaration, setAccessorDeclaration);
+        memberDoc = new PropertyMemberDoc(this.host, this, member, null, getAccessorDeclaration,
+            setAccessorDeclaration);
       }
 
       // If there is no member doc then we are in an interface or abstract class and we just take the first overload

typescript/src/api-doc-types/EnumExportDoc.ts

@@ -1,4 +1,5 @@
 import { Declaration, Symbol } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { ContainerExportDoc } from './ContainerExportDoc';
 import { ModuleDoc } from './ModuleDoc';
 
@@ -9,11 +10,12 @@ import { ModuleDoc } from './ModuleDoc';
 export class EnumExportDoc extends ContainerExportDoc {
   docType = 'enum';
   additionalDeclarations: Declaration[] = [];
-  constructor(
-    moduleDoc: ModuleDoc,
-    symbol: Symbol,
-    aliasSymbol?: Symbol) {
-    super(moduleDoc, symbol, symbol.valueDeclaration!, aliasSymbol);
+  constructor(host: Host,
+              moduleDoc: ModuleDoc,
+              symbol: Symbol,
+              aliasSymbol?: Symbol) {
+    super(host, moduleDoc, symbol, symbol.valueDeclaration!, aliasSymbol);
+
     this.additionalDeclarations = symbol.getDeclarations()!.filter(declaration => declaration !== this.declaration);
     if (symbol.exports) {
       this.members = this.getMemberDocs(symbol.exports, true);

typescript/src/api-doc-types/FunctionExportDoc.ts

@@ -1,4 +1,5 @@
 import { Declaration, Symbol } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { getDeclarationTypeText } from '../services/TsParser/getDeclarationTypeText';
 import { ModuleDoc } from './ModuleDoc';
 import { OverloadInfo } from './OverloadInfo';
@@ -18,11 +19,13 @@ export class FunctionExportDoc extends ParameterizedExportDoc implements Paramet
   readonly parameterDocs: ParameterDoc[] = getParameters(this);
   readonly parameters = this.parameterDocs.map(p => p.paramText);
 
-  constructor(
-      public containerDoc: ModuleDoc,
-      symbol: Symbol,
-      aliasSymbol?: Symbol) {
-    super(containerDoc, symbol, findRealDeclaration(symbol.getDeclarations()!), aliasSymbol);
+  constructor(host: Host,
+              public containerDoc: ModuleDoc,
+              symbol: Symbol,
+              aliasSymbol?: Symbol) {
+
+    super(host, containerDoc, symbol, findRealDeclaration(symbol.getDeclarations()!),
+        aliasSymbol);
   }
 
 }

typescript/src/api-doc-types/InterfaceExportDoc.ts

@@ -1,19 +1,28 @@
 import { Declaration, Symbol } from 'typescript';
 import { ClassLikeExportDoc } from '../api-doc-types/ClassLikeExportDoc';
 import { ModuleDoc } from '../api-doc-types/ModuleDoc';
+import { Host } from '../services/ts-host/host';
 
 /**
  * Interfaces are class-like but can also have multiple declarations that are merged together
  */
 export class InterfaceExportDoc extends ClassLikeExportDoc {
   docType = 'interface';
   additionalDeclarations: Declaration[] = [];
-  constructor(
-    moduleDoc: ModuleDoc,
-    symbol: Symbol,
-    aliasSymbol?: Symbol) {
-      super(moduleDoc, symbol, symbol.valueDeclaration || symbol.getDeclarations()![0]!, aliasSymbol);
-      if (symbol.members) this.members = this.getMemberDocs(symbol.members, true);
-      this.additionalDeclarations = symbol.getDeclarations()!.filter(declaration => declaration !== this.declaration);
+
+  constructor(host: Host,
+              moduleDoc: ModuleDoc,
+              symbol: Symbol,
+              aliasSymbol?: Symbol) {
+
+      super(host, moduleDoc, symbol, symbol.valueDeclaration || symbol.getDeclarations()![0]!,
+          aliasSymbol);
+
+      if (symbol.members) {
+        this.members = this.getMemberDocs(symbol.members, true);
+      }
+
+      this.additionalDeclarations = symbol.getDeclarations()!
+        .filter(declaration => declaration !== this.declaration);
     }
 }

typescript/src/api-doc-types/MemberDoc.ts

@@ -1,8 +1,8 @@
 /* tslint:disable:no-bitwise */
 import { Declaration, Symbol, SymbolFlags, SyntaxKind, TypeChecker } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { FileInfo } from '../services/TsParser/FileInfo';
 import { getAccessibility } from "../services/TsParser/getAccessibility";
-import { getContent } from "../services/TsParser/getContent";
 import { getDeclarationTypeText } from "../services/TsParser/getDeclarationTypeText";
 import { getDecorators, ParsedDecorator } from "../services/TsParser/getDecorators";
 import { ApiDoc } from './ApiDoc';
@@ -22,7 +22,7 @@ export abstract class MemberDoc implements ApiDoc {
 
   path: string = '';
   outputPath: string = '';
-  content = getContent(this.declaration);
+  content = this.host.getContent(this.declaration);
   basePath = this.containerDoc.basePath;
   fileInfo = new FileInfo(this.declaration, this.basePath);
   startingLine = this.fileInfo.location.start.line + (this.fileInfo.location.start.character ? 1 : 0);
@@ -43,6 +43,7 @@ export abstract class MemberDoc implements ApiDoc {
   isStatic = !!this.declaration.modifiers && this.declaration.modifiers.some(modifier => modifier.kind === SyntaxKind.StaticKeyword);
 
   constructor(
+      public host: Host,
       public containerDoc: ContainerExportDoc,
       public symbol: Symbol,
       public declaration: Declaration) {

typescript/src/api-doc-types/MethodMemberDoc.ts

@@ -1,5 +1,6 @@
 /* tslint:disable:no-bitwise */
 import { Declaration, Symbol } from 'typescript';
+import { Host } from '../services/ts-host/host';
 import { getTypeParametersText } from '../services/TsParser/getTypeParametersText';
 import { ContainerExportDoc } from './ContainerExportDoc';
 import { MemberDoc } from './MemberDoc';
@@ -15,12 +16,14 @@ export class MethodMemberDoc extends MemberDoc implements ParameterContainer {
   readonly aliases = this.computeAliases();
   readonly typeParameters = getTypeParametersText(this.declaration);
 
-  constructor(
-    containerDoc: ContainerExportDoc,
-    symbol: Symbol,
-    declaration: Declaration,
-    public overloads: MethodMemberDoc[] = []) {
-    super(containerDoc, symbol, declaration);
+  constructor(host: Host,
+              containerDoc: ContainerExportDoc,
+              symbol: Symbol,
+              declaration: Declaration,
+              public overloads: MethodMemberDoc[] = []) {
+
+    super(host, containerDoc, symbol, declaration);
+
     // fix up parameter ids and aliases, now that we have computed the id for this doc
     this.parameterDocs.forEach(param => {
       param.id = `${this.id}~${param.name}`;

typescript/src/api-doc-types/ModuleDoc.ts

@@ -23,5 +23,8 @@ export class ModuleDoc implements ApiDoc {
   outputPath: string = '';
   content: string = '';
 
-  constructor(public symbol: ModuleSymbol, public basePath: string, public hidePrivateMembers: boolean, public typeChecker: TypeChecker) {}
+  constructor(public symbol: ModuleSymbol,
+              public basePath: string,
+              public hidePrivateMembers: boolean,
+              public typeChecker: TypeChecker) {}
 }

typescript/src/api-doc-types/OverloadInfo.ts

@@ -1,10 +1,10 @@
 import { Declaration } from 'typescript';
 import { getDeclarationTypeText } from '../services/TsParser/getDeclarationTypeText';
+import { BaseApiDoc } from './ApiDoc';
 import { FunctionExportDoc } from './FunctionExportDoc';
 import { ModuleDoc } from './ModuleDoc';
 import { getParameters, ParameterContainer } from './ParameterContainer';
 import { ParameterDoc } from './ParameterDoc';
-import { BaseApiDoc } from './ApiDoc';
 
 /**
  * This represents a single overload of an exported function.
@@ -20,7 +20,8 @@ export class OverloadInfo extends BaseApiDoc implements ParameterContainer {
   containerDoc: ModuleDoc = this.functionDoc.containerDoc;
 
   constructor(public functionDoc: FunctionExportDoc, declaration: Declaration) {
-    super(functionDoc.moduleDoc, functionDoc.symbol, declaration);
+    super(functionDoc.host, functionDoc.moduleDoc, functionDoc.symbol, declaration);
+
     // Give this overload doc a more specific id and aliases than it's container doc
     const paramString = `(${this.parameters.join(', ')})`;
     this.id += paramString;