[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,7 @@
     "build": "heft test --clean"
   },
   "dependencies": {
-    "@microsoft/tsdoc": "0.12.24",
+    "@microsoft/tsdoc": "0.13.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

@@ -14,6 +14,18 @@ import { ApiDocumentedItem, IApiDocumentedItemOptions } from '../items/ApiDocume
 import { ApiEntryPoint } from './ApiEntryPoint';
 import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';
 import { DeserializerContext, ApiJsonSchemaVersion } from './DeserializerContext';
+import { TSDocConfiguration, TSDocTagDefinition, TSDocTagSyntaxKind } from '@microsoft/tsdoc';
+
+interface ITagConfigJson {
+  tagName: string;
+  syntaxKind: 'inline' | 'block' | 'modifier';
+  allowMultiple?: boolean;
+}
+
+interface ITSDocConfigJson {
+  tagDefinitions: ITagConfigJson[];
+  supportForTags: { [tagName: string]: boolean };
+}
 
 /**
  * Constructor options for {@link ApiPackage}.
@@ -22,7 +34,12 @@ import { DeserializerContext, ApiJsonSchemaVersion } from './DeserializerContext
 export interface IApiPackageOptions
   extends IApiItemContainerMixinOptions,
     IApiNameMixinOptions,
-    IApiDocumentedItemOptions {}
+    IApiDocumentedItemOptions {
+  /**
+   * The TSDoc tag definitions and support for the package
+   */
+  tsDocConfig: ITSDocConfigJson;
+}
 
 export interface IApiPackageMetadataJson {
   /**
@@ -58,6 +75,11 @@ export interface IApiPackageMetadataJson {
    * `IApiPackageMetadataJson.schemaVersion`.
    */
   oldestForwardsCompatibleVersion?: ApiJsonSchemaVersion;
+
+  /**
+   * The TSDoc tags used by the package
+   */
+  tsDocConfig: ITSDocConfigJson;
 }
 
 export interface IApiPackageJson extends IApiItemJson {
@@ -105,8 +127,15 @@ export interface IApiPackageSaveOptions extends IJsonFileSaveOptions {
  * @public
  */
 export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumentedItem)) {
+  /**
+   * TSDoc Tags for to the package.
+   */
+  private readonly _tsdocConfig: ITSDocConfigJson;
+
   public constructor(options: IApiPackageOptions) {
     super(options);
+
+    this._tsdocConfig = options.tsDocConfig;
   }
 
   public static loadFromJsonFile(apiJsonFilename: string): ApiPackage {
@@ -157,11 +186,35 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
       }
     }
 
+    const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
+    tsdocConfiguration.clear(true);
+    const { tagDefinitions, supportForTags } = jsonObject.metadata.tsDocConfig;
+    tsdocConfiguration.addTagDefinitions(
+      tagDefinitions.map((definition) => {
+        const { syntaxKind } = definition;
+        const formattedSyntaxKind: TSDocTagSyntaxKind =
+          syntaxKind === 'block'
+            ? TSDocTagSyntaxKind.BlockTag
+            : syntaxKind === 'inline'
+            ? TSDocTagSyntaxKind.InlineTag
+            : TSDocTagSyntaxKind.ModifierTag;
+        return new TSDocTagDefinition({ ...definition, syntaxKind: formattedSyntaxKind });
+      })
+    );
+
+    Object.entries(supportForTags).forEach(([name, supported]) => {
+      const tag: TSDocTagDefinition | undefined = tsdocConfiguration.tryGetTagDefinition(name);
+      if (tag) {
+        tsdocConfiguration.setSupportForTag(tag, supported);
+      }
+    });
+
     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;
@@ -208,7 +261,8 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
         // 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: this._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.
@@ -72,10 +74,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/package.json

@@ -35,7 +35,8 @@
   },
   "dependencies": {
     "@microsoft/api-extractor-model": "workspace:*",
-    "@microsoft/tsdoc": "0.12.24",
+    "@microsoft/tsdoc-config": "~0.14.0",
+    "@microsoft/tsdoc": "0.13.0",
     "@rushstack/node-core-library": "workspace:*",
     "@rushstack/rig-package": "workspace:*",
     "@rushstack/ts-command-line": "workspace:*",

apps/api-extractor/src/api/Extractor.ts

@@ -205,7 +205,8 @@ export class Extractor {
       messageCallback: options.messageCallback,
       messagesConfig: extractorConfig.messages || {},
       showVerboseMessages: !!options.showVerboseMessages,
-      showDiagnostics: !!options.showDiagnostics
+      showDiagnostics: !!options.showDiagnostics,
+      tsdocConfiguration: extractorConfig.tsdocConfiguration
     });
 
     this._checkCompilerCompatibility(extractorConfig, messageRouter);

apps/api-extractor/src/api/ExtractorConfig.ts

@@ -21,6 +21,8 @@ import { RigConfig } from '@rushstack/rig-package';
 import { IConfigFile, IExtractorMessagesConfig } from './IConfigFile';
 import { PackageMetadataManager } from '../analyzer/PackageMetadataManager';
 import { MessageRouter } from '../collector/MessageRouter';
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+import { TSDocConfigFile } from '@microsoft/tsdoc-config';
 
 /**
  * Tokens used during variable expansion of path fields from api-extractor.json.
@@ -149,6 +151,7 @@ interface IExtractorConfigParameters {
   omitTrimmingComments: boolean;
   tsdocMetadataEnabled: boolean;
   tsdocMetadataFilePath: string;
+  tsdocConfiguration: TSDocConfiguration;
   newlineKind: NewlineKind;
   messages: IExtractorMessagesConfig;
   testMode: boolean;
@@ -236,6 +239,11 @@ export class ExtractorConfig {
   /** {@inheritDoc IConfigTsdocMetadata.tsdocMetadataFilePath} */
   public readonly tsdocMetadataFilePath: string;
 
+  /**
+   * The TSDocConfiguration to use for parsing TSDoc comments
+   */
+  public readonly tsdocConfiguration: TSDocConfiguration;
+
   /**
    * Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files
    * will be written with Windows-style newlines.
@@ -269,6 +277,7 @@ export class ExtractorConfig {
     this.omitTrimmingComments = parameters.omitTrimmingComments;
     this.tsdocMetadataEnabled = parameters.tsdocMetadataEnabled;
     this.tsdocMetadataFilePath = parameters.tsdocMetadataFilePath;
+    this.tsdocConfiguration = parameters.tsdocConfiguration;
     this.newlineKind = parameters.newlineKind;
     this.messages = parameters.messages;
     this.testMode = parameters.testMode;
@@ -901,6 +910,18 @@ export class ExtractorConfig {
           break;
       }
 
+      const packageTSDocConfigPath: string = TSDocConfigFile.findConfigPathForFolder(projectFolder);
+      const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(
+        FileSystem.exists(packageTSDocConfigPath) ? packageTSDocConfigPath : __filename
+      );
+
+      if (tsdocConfigFile.hasErrors) {
+        throw new Error(tsdocConfigFile.getErrorSummary());
+      }
+
+      const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
+      tsdocConfigFile.configureParser(tsdocConfiguration);
+
       return new ExtractorConfig({
         projectFolder: projectFolder,
         packageJson,
@@ -922,6 +943,7 @@ export class ExtractorConfig {
         omitTrimmingComments,
         tsdocMetadataEnabled,
         tsdocMetadataFilePath,
+        tsdocConfiguration,
         newlineKind,
         messages: configObject.messages || {},
         testMode: !!configObject.testMode

apps/api-extractor/src/api/test/Extractor-custom-tags.test.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { StandardTags } from '@microsoft/tsdoc';
+import * as path from 'path';
+
+import { ExtractorConfig } from '../ExtractorConfig';
+
+const testDataFolder: string = path.join(__dirname, 'test-data');
+
+describe('Extractor-custom-tags', () => {
+  describe('should use a TSDocConfiguration', () => {
+    it.only("with custom TSDoc tags defined in the package's tsdoc.json", () => {
+      const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+        path.join(testDataFolder, 'custom-tsdoc-tags/api-extractor.json')
+      );
+      const { tsdocConfiguration } = extractorConfig;
+
+      expect(tsdocConfiguration.tryGetTagDefinition('@block')).not.toBe(undefined);
+      expect(tsdocConfiguration.tryGetTagDefinition('@inline')).not.toBe(undefined);
+      expect(tsdocConfiguration.tryGetTagDefinition('@modifier')).not.toBe(undefined);
+    });
+    it.only("with custom TSDoc tags enabled per the package's tsdoc.json", () => {
+      const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+        path.join(testDataFolder, 'custom-tsdoc-tags/api-extractor.json')
+      );
+      const { tsdocConfiguration } = extractorConfig;
+      const block = tsdocConfiguration.tryGetTagDefinition('@block')!;
+      const inline = tsdocConfiguration.tryGetTagDefinition('@inline')!;
+      const modifier = tsdocConfiguration.tryGetTagDefinition('@modifier')!;
+
+      expect(tsdocConfiguration.isTagSupported(block)).toBe(true);
+      expect(tsdocConfiguration.isTagSupported(inline)).toBe(true);
+      expect(tsdocConfiguration.isTagSupported(modifier)).toBe(false);
+    });
+    it.only("with standard tags and API Extractor custom tags defined and supported when the package's tsdoc.json extends API Extractor's tsdoc.json", () => {
+      const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+        path.join(testDataFolder, 'custom-tsdoc-tags/api-extractor.json')
+      );
+      const { tsdocConfiguration } = extractorConfig;
+
+      expect(tsdocConfiguration.tryGetTagDefinition('@inline')).not.toBe(undefined);
+      expect(tsdocConfiguration.tryGetTagDefinition('@block')).not.toBe(undefined);
+      expect(tsdocConfiguration.tryGetTagDefinition('@modifier')).not.toBe(undefined);
+
+      StandardTags.allDefinitions
+        .concat([
+          tsdocConfiguration.tryGetTagDefinition('@betaDocumentation')!,
+          tsdocConfiguration.tryGetTagDefinition('@internalRemarks')!,
+          tsdocConfiguration.tryGetTagDefinition('@preapproved')!
+        ])
+        .forEach((tag) => {
+          expect(tsdocConfiguration.tagDefinitions.includes(tag));
+          expect(tsdocConfiguration.supportedTagDefinitions.includes(tag));
+        });
+    });
+  });
+});

apps/api-extractor/src/api/test/test-data/custom-tsdoc-tags/api-extractor.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/index.d.ts",
+
+  "apiReport": {
+    "enabled": true
+  },
+
+  "docModel": {
+    "enabled": true
+  },
+
+  "dtsRollup": {
+    "enabled": true
+  }
+}

apps/api-extractor/src/api/test/test-data/custom-tsdoc-tags/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @block
+ *
+ * @inline test
+ * @modifier
+ */
+interface CustomTagsTestInterface {}

apps/api-extractor/src/api/test/test-data/custom-tsdoc-tags/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "config-lookup1",
+  "version": "1.0.0"
+}

apps/api-extractor/src/api/test/test-data/custom-tsdoc-tags/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src",
+
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react",
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "types": ["heft-jest", "node"],
+
+    "module": "commonjs",
+    "target": "es2017",
+    "lib": ["es2017"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules", "lib"]
+}