Add a new field "noStandardTags" to tsdoc.json, which is used to ensure that the TSDocConfigFile.saveFile() output does not conflict with predefined tags

tsdoc-config/src/TSDocConfigFile.ts

@@ -38,6 +38,7 @@ interface ITagConfigJson {
 interface IConfigJson {
   $schema: string;
   extends?: string[];
+  noStandardTags?: boolean;
   tagDefinitions?: ITagConfigJson[];
   supportForTags?: { [tagName: string]: boolean };
 }
@@ -64,6 +65,7 @@ export class TSDocConfigFile {
   private _hasErrors: boolean;
   private _tsdocSchema: string;
   private readonly _extendsPaths: string[];
+  private _noStandardTags: boolean | undefined;
   private readonly _tagDefinitions: TSDocTagDefinition[];
   private readonly _tagDefinitionNames: Set<string>;
   private readonly _supportForTags: Map<string, boolean>;
@@ -78,6 +80,7 @@ export class TSDocConfigFile {
     this._fileMTime = 0;
     this._tsdocSchema = '';
     this._extendsPaths = [];
+    this._noStandardTags = undefined;
     this._tagDefinitions = [];
     this._tagDefinitionNames = new Set();
     this._supportForTags = new Map();
@@ -133,6 +136,25 @@ export class TSDocConfigFile {
     return this._extendsPaths;
   }
 
+  /**
+   * By default, the config file loader will predefine all of the standardized TSDoc tags.  To disable this and
+   * start with a completely empty configuration, set `noStandardTags` to true.
+   *
+   * @remarks
+   * If a config file uses `"extends"` to include settings from base config files, then its setting will
+   * override any settings from the base config files.  If `"noStandardTags"` is not specified, then this
+   * property will be `undefined`.  The config files are applied in the order they are processed (a depth-first
+   * traversal of the `"extends"` references), and files processed later can override earlier files.
+   * If no config file specifies `noStandardTags` then the default value is `false`.
+   */
+  public get noStandardTags(): boolean | undefined {
+    return this._noStandardTags;
+  }
+
+  public set noStandardTags(value: boolean | undefined) {
+    this._noStandardTags = value;
+  }
+
   public get tagDefinitions(): ReadonlyArray<TSDocTagDefinition> {
     return this._tagDefinitions;
   }
@@ -288,6 +310,8 @@ export class TSDocConfigFile {
       this._extendsPaths.push(...configJson.extends);
     }
 
+    this.noStandardTags = configJson.noStandardTags;
+
     for (const jsonTagDefinition of configJson.tagDefinitions || []) {
       let syntaxKind: TSDocTagSyntaxKind;
       switch (jsonTagDefinition.syntaxKind) {
@@ -444,6 +468,10 @@ export class TSDocConfigFile {
   public static loadFromParser(configuration: TSDocConfiguration): TSDocConfigFile {
     const configFile: TSDocConfigFile = new TSDocConfigFile();
 
+    // The standard tags will be mixed together with custom definitions,
+    // so set noStandardTags=true to avoid defining them twice.
+    configFile.noStandardTags = true;
+
     for (const tagDefinition of configuration.tagDefinitions) {
       configFile.addTagDefinition({
         syntaxKind: tagDefinition.syntaxKind,
@@ -476,6 +504,10 @@ export class TSDocConfigFile {
       $schema: TSDocConfigFile.CURRENT_SCHEMA_URL,
     };
 
+    if (this.noStandardTags !== undefined) {
+      configJson.noStandardTags = this.noStandardTags;
+    }
+
     if (this.tagDefinitions.length > 0) {
       configJson.tagDefinitions = [];
       for (const tagDefinition of this.tagDefinitions) {
@@ -551,9 +583,24 @@ export class TSDocConfigFile {
    * Any `extendsFile` settings will also applied.
    */
   public configureParser(configuration: TSDocConfiguration): void {
+    if (this._getNoStandardTagsWithExtends()) {
+      // Do not define standard tags
+      configuration.clear(true);
+    } else {
+      // Define standard tags (the default behavior)
+      configuration.clear(false);
+    }
+
+    this.updateParser(configuration);
+  }
+
+  /**
+   * This is the same as {@link configureParser}, but it preserves any previous state.
+   */
+  public updateParser(configuration: TSDocConfiguration): void {
     // First apply the base config files
     for (const extendsFile of this.extendsFiles) {
-      extendsFile.configureParser(configuration);
+      extendsFile.updateParser(configuration);
     }
 
     // Then apply this one
@@ -575,4 +622,26 @@ export class TSDocConfigFile {
       }
     });
   }
+
+  private _getNoStandardTagsWithExtends(): boolean {
+    if (this.noStandardTags !== undefined) {
+      return this.noStandardTags;
+    }
+
+    // This config file does not specify "noStandardTags", so consider any base files referenced using "extends"
+    let result: boolean | undefined = undefined;
+    for (const extendsFile of this.extendsFiles) {
+      const extendedValue: boolean | undefined = extendsFile._getNoStandardTagsWithExtends();
+      if (extendedValue !== undefined) {
+        result = extendedValue;
+      }
+    }
+
+    if (result === undefined) {
+      // If no config file specifies noStandardTags, then it defaults to false
+      result = false;
+    }
+
+    return result;
+  }
 }

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

@@ -21,6 +21,7 @@ expect.addSnapshotSerializer({
       fileNotFound: configFile.fileNotFound,
       extendsPaths: configFile.extendsPaths,
       extendsFiles: configFile.extendsFiles,
+      noStandardTags: configFile.noStandardTags,
       tagDefinitions: configFile.tagDefinitions,
       supportForTags: Array.from(configFile.supportForTags).map(([tagName, supported]) => ({ tagName, supported })),
       messages: configFile.log.messages,
@@ -40,6 +41,7 @@ test('Load p1', () => {
       "fileNotFound": false,
       "filePath": "assets/p1/tsdoc.json",
       "messages": Array [],
+      "noStandardTags": undefined,
       "supportForTags": Array [],
       "tagDefinitions": Array [],
       "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
@@ -68,6 +70,7 @@ test('Load p2', () => {
           "unformattedText": "File not found",
         },
       ],
+      "noStandardTags": undefined,
       "supportForTags": Array [],
       "tagDefinitions": Array [],
       "tsdocSchema": "",
@@ -85,6 +88,7 @@ test('Load p3', () => {
           "fileNotFound": false,
           "filePath": "assets/p3/base1/tsdoc-base1.json",
           "messages": Array [],
+          "noStandardTags": undefined,
           "supportForTags": Array [
             Object {
               "supported": true,
@@ -108,6 +112,7 @@ test('Load p3', () => {
           "fileNotFound": false,
           "filePath": "assets/p3/base2/tsdoc-base2.json",
           "messages": Array [],
+          "noStandardTags": undefined,
           "supportForTags": Array [
             Object {
               "supported": false,
@@ -133,6 +138,7 @@ test('Load p3', () => {
       "fileNotFound": false,
       "filePath": "assets/p3/tsdoc.json",
       "messages": Array [],
+      "noStandardTags": undefined,
       "supportForTags": Array [
         Object {
           "supported": true,
@@ -163,6 +169,7 @@ test('Load p4', () => {
           "fileNotFound": false,
           "filePath": "assets/p4/node_modules/example-lib/dist/tsdoc-example.json",
           "messages": Array [],
+          "noStandardTags": undefined,
           "supportForTags": Array [],
           "tagDefinitions": Array [
             TSDocTagDefinition {
@@ -182,6 +189,7 @@ test('Load p4', () => {
       "fileNotFound": false,
       "filePath": "assets/p4/tsdoc.json",
       "messages": Array [],
+      "noStandardTags": undefined,
       "supportForTags": Array [],
       "tagDefinitions": Array [
         TSDocTagDefinition {
@@ -197,7 +205,7 @@ test('Load p4', () => {
   `);
 });
 
-test('Re-serialize p2', () => {
+test('Re-serialize p3', () => {
   const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p3'));
   // This is the data from p3/tsdoc.json, ignoring its "extends" field.
   expect(configFile.saveToObject()).toMatchInlineSnapshot(`
@@ -216,7 +224,7 @@ test('Re-serialize p2', () => {
   `);
 });
 
-test('Re-serialize p2 without defaults', () => {
+test('Re-serialize p3 without defaults', () => {
   const parserConfiguration: TSDocConfiguration = new TSDocConfiguration();
   parserConfiguration.clear(true);
 
@@ -225,10 +233,12 @@ test('Re-serialize p2 without defaults', () => {
   expect(defaultsConfigFile.saveToObject()).toMatchInlineSnapshot(`
     Object {
       "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+      "noStandardTags": true,
     }
   `);
 
   const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p3'));
+  configFile.noStandardTags = true;
   configFile.configureParser(parserConfiguration);
 
   const mergedConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromParser(parserConfiguration);
@@ -238,6 +248,7 @@ test('Re-serialize p2 without defaults', () => {
   expect(mergedConfigFile.saveToObject()).toMatchInlineSnapshot(`
     Object {
       "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+      "noStandardTags": true,
       "supportForTags": Object {
         "@base1": true,
         "@base2": true,
@@ -260,7 +271,7 @@ test('Re-serialize p2 without defaults', () => {
   `);
 });
 
-test('Re-serialize p2 with defaults', () => {
+test('Re-serialize p3 with defaults', () => {
   const parserConfiguration: TSDocConfiguration = new TSDocConfiguration();
 
   const defaultsConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromParser(parserConfiguration);
@@ -268,6 +279,7 @@ test('Re-serialize p2 with defaults', () => {
   expect(defaultsConfigFile.saveToObject()).toMatchInlineSnapshot(`
     Object {
       "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+      "noStandardTags": true,
       "tagDefinitions": Array [
         Object {
           "syntaxKind": "modifier",
@@ -389,6 +401,7 @@ test('Re-serialize p2 with defaults', () => {
   expect(mergedConfigFile.saveToObject()).toMatchInlineSnapshot(`
     Object {
       "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+      "noStandardTags": true,
       "supportForTags": Object {
         "@base1": true,
         "@base2": true,
@@ -516,3 +529,23 @@ test('Re-serialize p2 with defaults', () => {
     }
   `);
 });
+
+test('Test noStandardTags for p5', () => {
+  const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p5'));
+
+  const configuration: TSDocConfiguration = new TSDocConfiguration();
+  configFile.configureParser(configuration);
+
+  // noStandardTags=true because tsdoc-base2.json overrides tsdoc-base1.json, and tsdoc.json is undefined
+  expect(configuration.tagDefinitions.length).toEqual(0);
+});
+
+test('Test noStandardTags for p6', () => {
+  const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p6'));
+
+  const configuration: TSDocConfiguration = new TSDocConfiguration();
+  configFile.configureParser(configuration);
+
+  // noStandardTags=false  because tsdoc.json  overrides tsdoc-base1.json
+  expect(configuration.tagDefinitions.length).toBeGreaterThan(0);
+});

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

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "noStandardTags": false
+}

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

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "noStandardTags": true
+}

tsdoc-config/src/__tests__/assets/p5/tsconfig.json

@@ -0,0 +1 @@
+{}

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

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": ["./base1/tsdoc-base1.json", "./base2/tsdoc-base2.json"]
+}

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

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "noStandardTags": true
+}

tsdoc-config/src/__tests__/assets/p6/tsconfig.json

@@ -0,0 +1 @@
+{}

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

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": ["./base1/tsdoc-base1.json"],
+  "noStandardTags": false
+}

tsdoc/schemas/tsdoc.schema.json

@@ -16,6 +16,11 @@
       }
     },
 
+    "noStandardTags": {
+      "description": "By default, the config file loader will predefine all of the standardized TSDoc tags.  To disable this and start with a completely empty configuration, set \"noStandardTags\"=true.",
+      "type": "boolean"
+    },
+
     "tagDefinitions": {
       "description": "Additional tags to support when parsing documentation comments with TSDoc.",
       "type": "array",