Implement "supportForTags" field in tsdoc.json

tsdoc-config/src/TSDocConfigFile.ts

@@ -38,7 +38,8 @@ interface IConfigJson {
   $schema: string;
   tsdocVersion: string;
   extends?: string[];
-  tagDefinitions: ITagConfigJson[];
+  tagDefinitions?: ITagConfigJson[];
+  supportForTags?: { [tagName: string]: boolean };
 }
 
 /**
@@ -64,6 +65,7 @@ export class TSDocConfigFile {
   private _tsdocSchema: string;
   private readonly _extendsPaths: string[];
   private readonly _tagDefinitions: TSDocTagDefinition[];
+  private readonly _supportForTags: Map<string, boolean>;
 
   private constructor() {
     this.log = new ParserMessageLog();
@@ -76,6 +78,7 @@ export class TSDocConfigFile {
     this._tsdocSchema = '';
     this._extendsPaths = [];
     this._tagDefinitions = [];
+    this._supportForTags = new Map();
   }
 
   /**
@@ -132,6 +135,10 @@ export class TSDocConfigFile {
     return this._tagDefinitions;
   }
 
+  public get supportForTags(): ReadonlyMap<string, boolean> {
+    return this._supportForTags;
+  }
+
   /**
    * This can be used for cache eviction.  It returns true if the modification timestamp has changed for
    * any of the files that were read when loading this `TSDocConfigFile`, which indicates that the file should be
@@ -238,6 +245,14 @@ export class TSDocConfigFile {
         })
       );
     }
+
+    if (configJson.supportForTags) {
+      for (const tagName of Object.keys(configJson.supportForTags)) {
+        const supported: boolean = configJson.supportForTags[tagName];
+
+        this._supportForTags.set(tagName, supported);
+      }
+    }
   }
 
   private _loadWithExtends(
@@ -398,5 +413,19 @@ export class TSDocConfigFile {
     for (const tagDefinition of this.tagDefinitions) {
       configuration.addTagDefinition(tagDefinition);
     }
+
+    this.supportForTags.forEach((supported: boolean, tagName: string) => {
+      const tagDefinition: TSDocTagDefinition | undefined = configuration.tryGetTagDefinition(tagName);
+      if (tagDefinition) {
+        // Note that setSupportForTag() automatically enables configuration.validation.reportUnsupportedTags
+        configuration.setSupportForTag(tagDefinition, supported);
+      } else {
+        this._reportError({
+          messageId: TSDocMessageId.ConfigFileUndefinedTag,
+          messageText: `The "supportForTags" field refers to an undefined tag ${JSON.stringify(tagName)}.`,
+          textRange: TextRange.empty,
+        });
+      }
+    });
   }
 }

tsdoc-config/src/__tests__/TSDocConfigFile.test.ts

@@ -21,6 +21,7 @@ expect.addSnapshotSerializer({
       extendsPaths: configFile.extendsPaths,
       extendsFiles: configFile.extendsFiles,
       tagDefinitions: configFile.tagDefinitions,
+      supportForTags: Array.from(configFile.supportForTags).map(([tagName, supported]) => ({ tagName, supported })),
       messages: configFile.log.messages,
     });
   },
@@ -38,6 +39,7 @@ test('Load p1', () => {
       "fileNotFound": false,
       "filePath": "assets/p1/tsdoc.json",
       "messages": Array [],
+      "supportForTags": Array [],
       "tagDefinitions": Array [],
       "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
     }
@@ -64,6 +66,7 @@ test('Load p2', () => {
           "unformattedText": "File not found",
         },
       ],
+      "supportForTags": Array [],
       "tagDefinitions": Array [],
       "tsdocSchema": "",
     }
@@ -79,6 +82,12 @@ test('Load p3', () => {
           "fileNotFound": false,
           "filePath": "assets/p3/base1/tsdoc-base1.json",
           "messages": Array [],
+          "supportForTags": Array [
+            Object {
+              "supported": true,
+              "tagName": "@base1",
+            },
+          ],
           "tagDefinitions": Array [
             TSDocTagDefinition {
               "allowMultiple": false,
@@ -96,6 +105,12 @@ test('Load p3', () => {
           "fileNotFound": false,
           "filePath": "assets/p3/base2/tsdoc-base2.json",
           "messages": Array [],
+          "supportForTags": Array [
+            Object {
+              "supported": false,
+              "tagName": "@base2",
+            },
+          ],
           "tagDefinitions": Array [
             TSDocTagDefinition {
               "allowMultiple": false,
@@ -115,6 +130,12 @@ test('Load p3', () => {
       "fileNotFound": false,
       "filePath": "assets/p3/tsdoc.json",
       "messages": Array [],
+      "supportForTags": Array [
+        Object {
+          "supported": true,
+          "tagName": "@base2",
+        },
+      ],
       "tagDefinitions": Array [
         TSDocTagDefinition {
           "allowMultiple": false,
@@ -138,6 +159,7 @@ test('Load p4', () => {
           "fileNotFound": false,
           "filePath": "assets/p4/node_modules/example-lib/dist/tsdoc-example.json",
           "messages": Array [],
+          "supportForTags": Array [],
           "tagDefinitions": Array [
             TSDocTagDefinition {
               "allowMultiple": false,
@@ -156,6 +178,7 @@ test('Load p4', () => {
       "fileNotFound": false,
       "filePath": "assets/p4/tsdoc.json",
       "messages": Array [],
+      "supportForTags": Array [],
       "tagDefinitions": Array [
         TSDocTagDefinition {
           "allowMultiple": false,

tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json

@@ -5,5 +5,8 @@
       "tagName": "@base1",
       "syntaxKind": "modifier"
     }
-  ]
+  ],
+  "supportForTags": {
+    "@base1": true
+  }
 }

tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json

@@ -5,5 +5,8 @@
       "tagName": "@base2",
       "syntaxKind": "modifier"
     }
-  ]
+  ],
+  "supportForTags": {
+    "@base2": false
+  }
 }

tsdoc-config/src/__tests__/assets/p3/tsdoc.json

@@ -6,5 +6,8 @@
       "tagName": "@root",
       "syntaxKind": "modifier"
     }
-  ]
+  ],
+  "supportForTags": {
+    "@base2": true
+  }
 }

tsdoc/schemas/tsdoc.schema.json

@@ -22,6 +22,17 @@
       "items": {
         "$ref": "#/definitions/tsdocTagDefinition"
       }
+    },
+
+    "supportForTags": {
+      "description": "A collection of key/value pairs.  The key is a TSDoc tag name (e.g. \"@myTag\") that must be defined in this configuration.  The value is a boolean indicating whether the tag is supported.  The TSDoc parser may report warnings when unsupported tags are encountered.  If \"supportForTags\" is specified for at least one tag, then the \"reportUnsupportedTags\" validation check is enabled by default.",
+      "type": "object",
+      "patternProperties": {
+        "@[a-zA-Z][a-zA-Z0-9]*$": {
+          "type": "boolean"
+        }
+      },
+      "additionalItems": false
     }
   },
   "required": ["$schema"],

tsdoc/src/parser/TSDocMessageId.ts

@@ -46,6 +46,11 @@ export const enum TSDocMessageId {
    */
   ConfigFileUnresolvedExtends = 'tsdoc-config-unresolved-extends',
 
+  /**
+   * The "supportForTags" field refers to an undefined tag "___".
+   */
+  ConfigFileUndefinedTag = 'tsdoc-config-undefined-tag',
+
   /**
    * Expecting a `/**` comment.
    * Unexpected end of input.
@@ -389,6 +394,8 @@ export const allTsdocMessageIds: string[] = [
   'tsdoc-config-schema-error',
   'tsdoc-config-cyclic-extends',
   'tsdoc-config-unresolved-extends',
+  'tsdoc-config-undefined-tag',
+
   'tsdoc-comment-not-found',
   'tsdoc-comment-missing-opening-delimiter',
   'tsdoc-comment-missing-closing-delimiter',