[api-extractor] Adds package-defined TSDoc tag support

apps/api-documenter/package.json

@@ -18,7 +18,7 @@
   "typings": "dist/rollup.d.ts",
   "dependencies": {
     "@microsoft/api-extractor-model": "workspace:*",
-    "@microsoft/tsdoc": "0.12.24",
+    "@microsoft/tsdoc": "0.13.0",
     "@rushstack/node-core-library": "workspace:*",
     "@rushstack/ts-command-line": "workspace:*",
     "colors": "~1.2.1",

apps/api-extractor-model/package.json

@@ -14,7 +14,8 @@
     "build": "heft test --clean"
   },
   "dependencies": {
-    "@microsoft/tsdoc": "0.12.24",
+    "@microsoft/tsdoc": "0.13.0",
+    "@microsoft/tsdoc-config": "~0.15.0",
     "@rushstack/node-core-library": "workspace:*"
   },
   "devDependencies": {

apps/api-extractor-model/src/aedoc/AedocDefinitions.ts

@@ -5,6 +5,7 @@ import { TSDocConfiguration, TSDocTagDefinition, TSDocTagSyntaxKind, StandardTag
 
 /**
  * @internal
+ * @deprecated - tsdoc configuration is now constructed from tsdoc.json files associated with each package.
  */
 export class AedocDefinitions {
   public static readonly betaDocumentation: TSDocTagDefinition = new TSDocTagDefinition({

apps/api-extractor-model/src/items/ApiDocumentedItem.ts

@@ -3,7 +3,6 @@
 
 import * as tsdoc from '@microsoft/tsdoc';
 import { ApiItem, IApiItemOptions, IApiItemJson } from './ApiItem';
-import { AedocDefinitions } from '../aedoc/AedocDefinitions';
 import { DeserializerContext } from '../model/DeserializerContext';
 
 /**
@@ -47,7 +46,7 @@ export class ApiDocumentedItem extends ApiItem {
     const documentedJson: IApiDocumentedItemJson = jsonObject as IApiDocumentedItemJson;
 
     if (documentedJson.docComment) {
-      const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(AedocDefinitions.tsdocConfiguration);
+      const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(context.tsdocConfiguration);
 
       // NOTE: For now, we ignore TSDoc errors found in a serialized .api.json file.
       // Normally these errors would have already been reported by API Extractor during analysis.

apps/api-extractor-model/src/model/ApiPackage.ts

@@ -8,12 +8,15 @@ import {
   JsonFile,
   IJsonFileSaveOptions,
   PackageJsonLookup,
-  IPackageJson
+  IPackageJson,
+  JsonObject
 } from '@rushstack/node-core-library';
 import { ApiDocumentedItem, IApiDocumentedItemOptions } from '../items/ApiDocumentedItem';
 import { ApiEntryPoint } from './ApiEntryPoint';
 import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';
 import { DeserializerContext, ApiJsonSchemaVersion } from './DeserializerContext';
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+import { TSDocConfigFile } from '@microsoft/tsdoc-config';
 
 /**
  * Constructor options for {@link ApiPackage}.
@@ -22,7 +25,9 @@ import { DeserializerContext, ApiJsonSchemaVersion } from './DeserializerContext
 export interface IApiPackageOptions
   extends IApiItemContainerMixinOptions,
     IApiNameMixinOptions,
-    IApiDocumentedItemOptions {}
+    IApiDocumentedItemOptions {
+  tsdocConfiguration: TSDocConfiguration;
+}
 
 export interface IApiPackageMetadataJson {
   /**
@@ -58,6 +63,17 @@ export interface IApiPackageMetadataJson {
    * `IApiPackageMetadataJson.schemaVersion`.
    */
   oldestForwardsCompatibleVersion?: ApiJsonSchemaVersion;
+
+  /**
+   * The TSDoc configuration that was used when analyzing the API for this package.
+   *
+   * @remarks
+   *
+   * The structure of this objet is defined by the `@microsoft/tsdoc-config` library.
+   * Normally this configuration is loaded from the project's tsdoc.json file.  It is stored
+   * in the .api.json file so that doc comments can be parsed accurately when loading the file.
+   */
+  tsdocConfig: JsonObject;
 }
 
 export interface IApiPackageJson extends IApiItemJson {
@@ -105,8 +121,12 @@ export interface IApiPackageSaveOptions extends IJsonFileSaveOptions {
  * @public
  */
 export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumentedItem)) {
+  private readonly _tsdocConfiguration: TSDocConfiguration;
+
   public constructor(options: IApiPackageOptions) {
     super(options);
+
+    this._tsdocConfiguration = options.tsdocConfiguration;
   }
 
   public static loadFromJsonFile(apiJsonFilename: string): ApiPackage {
@@ -157,11 +177,25 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
       }
     }
 
+    const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
+
+    if (versionToDeserialize >= ApiJsonSchemaVersion.V_1004) {
+      const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromObject(
+        jsonObject.metadata.tsdocConfig
+      );
+      if (tsdocConfigFile.hasErrors) {
+        throw new Error(`Error loading ${apiJsonFilename}:\n` + tsdocConfigFile.getErrorSummary());
+      }
+
+      tsdocConfigFile.configureParser(tsdocConfiguration);
+    }
+
     const context: DeserializerContext = new DeserializerContext({
       apiJsonFilename,
       toolPackage: jsonObject.metadata.toolPackage,
       toolVersion: jsonObject.metadata.toolVersion,
-      versionToDeserialize: versionToDeserialize
+      versionToDeserialize: versionToDeserialize,
+      tsdocConfiguration
     });
 
     return ApiItem.deserialize(jsonObject, context) as ApiPackage;
@@ -182,6 +216,18 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
     return this.members as ReadonlyArray<ApiEntryPoint>;
   }
 
+  /**
+   * The TSDoc configuration that was used when analyzing the API for this package.
+   *
+   * @remarks
+   *
+   * Normally this configuration is loaded from the project's tsdoc.json file.  It is stored
+   * in the .api.json file so that doc comments can be parsed accurately when loading the file.
+   */
+  public get tsdocConfiguration(): TSDocConfiguration {
+    return this._tsdocConfiguration;
+  }
+
   /** @override */
   public addMember(member: ApiEntryPoint): void {
     if (member.kind !== ApiItemKind.EntryPoint) {
@@ -201,14 +247,18 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
 
     const packageJson: IPackageJson = PackageJsonLookup.loadOwnPackageJson(__dirname);
 
+    const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromParser(this.tsdocConfiguration);
+    const tsdocConfig: JsonObject = tsdocConfigFile.saveToObject();
+
     const jsonObject: IApiPackageJson = {
       metadata: {
         toolPackage: options.toolPackage || packageJson.name,
         // In test mode, we don't write the real version, since that would cause spurious diffs whenever
         // the version is bumped.  Instead we write a placeholder string.
         toolVersion: options.testMode ? '[test mode]' : options.toolVersion || packageJson.version,
         schemaVersion: ApiJsonSchemaVersion.LATEST,
-        oldestForwardsCompatibleVersion: ApiJsonSchemaVersion.OLDEST_FORWARDS_COMPATIBLE
+        oldestForwardsCompatibleVersion: ApiJsonSchemaVersion.OLDEST_FORWARDS_COMPATIBLE,
+        tsdocConfig
       }
     } as IApiPackageJson;
     this.serializeInto(jsonObject);

apps/api-extractor-model/src/model/DeserializerContext.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+
 export enum ApiJsonSchemaVersion {
   /**
    * The initial release.
@@ -25,13 +27,21 @@ export enum ApiJsonSchemaVersion {
    */
   V_1003 = 1003,
 
+  /**
+   * Add a "tsdocConfig" field that tracks the TSDoc configuration for parsing doc comments.
+   *
+   * This is not a breaking change because an older implementation will still work correctly.  The
+   * custom tags will be skipped over by the parser.
+   */
+  V_1004 = 1004,
+
   /**
    * The current latest .api.json schema version.
    *
    * IMPORTANT: When incrementing this number, consider whether `OLDEST_SUPPORTED` or `OLDEST_FORWARDS_COMPATIBLE`
    * should be updated.
    */
-  LATEST = V_1003,
+  LATEST = V_1004,
 
   /**
    * The oldest .api.json schema version that is still supported for backwards compatibility.
@@ -72,10 +82,16 @@ export class DeserializerContext {
    */
   public readonly versionToDeserialize: ApiJsonSchemaVersion;
 
+  /**
+   * The TSDoc configuration for the context.
+   */
+  public readonly tsdocConfiguration: TSDocConfiguration;
+
   public constructor(options: DeserializerContext) {
     this.apiJsonFilename = options.apiJsonFilename;
     this.toolPackage = options.toolPackage;
     this.toolVersion = options.toolVersion;
     this.versionToDeserialize = options.versionToDeserialize;
+    this.tsdocConfiguration = options.tsdocConfiguration;
   }
 }

apps/api-extractor/.npmignore

@@ -27,4 +27,6 @@
 # DO NOT MODIFY THE TEMPLATE ABOVE THIS LINE
 #--------------------------------------------
 
-# (Add your project-specific overrides here)
+# (Add your project-specific overrides here)
+
+!/extends/*.json

apps/api-extractor/.vscode/launch.json

@@ -4,17 +4,23 @@
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Jest tests",
+      "program": "${workspaceFolder}/node_modules/@rushstack/heft/lib/start.js",
+      "cwd": "${workspaceFolder}",
+      "args": ["--debug", "test", "--clean"],
+      "console": "integratedTerminal",
+      "sourceMaps": true
+    },
     {
       "type": "node",
       "request": "launch",
       "name": "Run in specified folder",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "(your project path)",
-      "args": [
-        "--debug",
-        "run",
-        "--local"
-      ],
+      "args": ["--debug", "run", "--local"],
       "sourceMaps": true
     },
     {
@@ -23,11 +29,7 @@
       "name": "test-01",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-01",
-      "args": [
-        "--debug",
-        "run",
-        "--local"
-      ],
+      "args": ["--debug", "run", "--local"],
       "sourceMaps": true
     },
     {
@@ -36,11 +38,7 @@
       "name": "test-02",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-02",
-      "args": [
-        "--debug",
-        "run",
-        "--local"
-      ],
+      "args": ["--debug", "run", "--local"],
       "sourceMaps": true
     },
     {
@@ -49,11 +47,7 @@
       "name": "test-03",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-03",
-      "args": [
-        "--debug",
-        "run",
-        "--local"
-      ],
+      "args": ["--debug", "run", "--local"],
       "sourceMaps": true
     },
     {
@@ -62,11 +56,7 @@
       "name": "test-04",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-04",
-      "args": [
-        "--debug",
-        "run",
-        "--local"
-      ],
+      "args": ["--debug", "run", "--local"],
       "sourceMaps": true
     },
     {
@@ -75,11 +65,7 @@
       "name": "test-05",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-05",
-      "args": [
-        "--debug",
-        "run",
-        "--local"
-      ],
+      "args": ["--debug", "run", "--local"],
       "sourceMaps": true
     },
     {
@@ -88,13 +74,7 @@
       "name": "scenario",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-scenarios",
-      "args": [
-        "--debug",
-        "run",
-        "--local",
-        "--config",
-        "./temp/configs/api-extractor-typeof.json"
-      ],
+      "args": ["--debug", "run", "--local", "--config", "./temp/configs/api-extractor-typeof.json"],
       "sourceMaps": true
     }
   ]