build: fix errors due to unknown JSDoc tags in API doc generation

In order to be able to merge class members from extended classes,
we currently have some special logic to resolve Dgeni API docs manually
through the type checker and TypeScript AST.

This logic works fine so far, but breaks the JSDoc parse processor after
the recent dgeni-packages update. The JSDoc parser breaks because we resolved
external source files (not part of our base path) that use other JSDoc
tags/annotations which are not supported/known to our Angular Material docs
generation.

This commit filters out such docs before adding them to the Dgeni pipeline.

Additionally adds a couple of tags/annotations which are not supported by
Dgeni, but used in our generation.

Author: devversion

tools/dgeni/common/class-inheritance.ts

@@ -8,7 +8,9 @@ import * as ts from 'typescript';
 import {MemberDoc} from 'dgeni-packages/typescript/api-doc-types/MemberDoc';
 
 /** Type describing class like documents which have been created through inheritance. */
-export type InheritanceCreatedClassLikeDoc = ClassLikeExportDoc & {_inheritanceCreated?: true};
+export type InheritanceCreatedClassLikeDoc = ClassLikeExportDoc & {
+  _inheritanceCreated?: true;
+};
 
 /** Whether the given API doc has been created through inheritance. */
 export function isInheritanceCreatedDoc(doc: ApiDoc): doc is ClassLikeExportDoc {

tools/dgeni/docs-package.ts

@@ -95,6 +95,11 @@ apiDocsPackage.config(function (parseTagsProcessor: any) {
     {name: 'docs-public'},
     {name: 'docs-primary-export'},
     {name: 'breaking-change'},
+    // Adds support for the `tsdoc` `@template` annotation/tag.
+    // https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template.
+    {name: 'template', multi: true},
+    //  JSDoc annotations/tags which are not supported by default.
+    {name: 'throws', multi: true},
   ]);
 });
 

tools/dgeni/processors/resolve-inherited-docs.ts

@@ -44,6 +44,14 @@ export class ResolveInheritedDocs implements Processor {
         if (!isInheritanceCreatedDoc(apiDoc)) {
           return;
         }
+        // If this is an external document not part of our sources, we will not add it to the
+        // Dgeni API doc pipeline. Docs would be filtered regardless, but adding them to the
+        // pipeline could cause e.g. the JSDoc parser to complain about tags/annotations which
+        // are not known/relevant to our API docs. e.g. Framework uses `@nodoc` or `@usageNotes`.
+        if (apiDoc.fileInfo.projectRelativePath.startsWith('../')) {
+          return;
+        }
+
         // Add the member docs for the inherited doc to the Dgeni doc collection.
         this._getContainingMemberDocs(apiDoc).forEach(d => newDocs.add(d));
         // Add the class-like export doc to the Dgeni doc collection.