From c0727781fe5ca261b9f05bc201d64b69270a3123 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Thu, 21 Jan 2021 21:58:04 -0800 Subject: [PATCH 1/4] 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 | 71 ++++++++++++++++++- .../src/__tests__/TSDocConfigFile.test.ts | 39 +++++++++- .../assets/p5/base1/tsdoc-base1.json | 4 ++ .../assets/p5/base2/tsdoc-base2.json | 4 ++ .../src/__tests__/assets/p5/tsconfig.json | 1 + .../src/__tests__/assets/p5/tsdoc.json | 4 ++ .../assets/p6/base1/tsdoc-base1.json | 4 ++ .../src/__tests__/assets/p6/tsconfig.json | 1 + .../src/__tests__/assets/p6/tsdoc.json | 5 ++ tsdoc/schemas/tsdoc.schema.json | 5 ++ 10 files changed, 134 insertions(+), 4 deletions(-) create mode 100644 tsdoc-config/src/__tests__/assets/p5/base1/tsdoc-base1.json create mode 100644 tsdoc-config/src/__tests__/assets/p5/base2/tsdoc-base2.json create mode 100644 tsdoc-config/src/__tests__/assets/p5/tsconfig.json create mode 100644 tsdoc-config/src/__tests__/assets/p5/tsdoc.json create mode 100644 tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-base1.json create mode 100644 tsdoc-config/src/__tests__/assets/p6/tsconfig.json create mode 100644 tsdoc-config/src/__tests__/assets/p6/tsdoc.json diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 3197bc6e..a20265d0 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/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; private readonly _supportForTags: Map; @@ -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 { 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; + } } diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index 25ac5dc9..c13f2c17 100644 --- a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts +++ b/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); +}); diff --git a/tsdoc-config/src/__tests__/assets/p5/base1/tsdoc-base1.json b/tsdoc-config/src/__tests__/assets/p5/base1/tsdoc-base1.json new file mode 100644 index 00000000..533fcb5d --- /dev/null +++ b/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 +} diff --git a/tsdoc-config/src/__tests__/assets/p5/base2/tsdoc-base2.json b/tsdoc-config/src/__tests__/assets/p5/base2/tsdoc-base2.json new file mode 100644 index 00000000..17acb7ca --- /dev/null +++ b/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 +} diff --git a/tsdoc-config/src/__tests__/assets/p5/tsconfig.json b/tsdoc-config/src/__tests__/assets/p5/tsconfig.json new file mode 100644 index 00000000..0967ef42 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p5/tsconfig.json @@ -0,0 +1 @@ +{} diff --git a/tsdoc-config/src/__tests__/assets/p5/tsdoc.json b/tsdoc-config/src/__tests__/assets/p5/tsdoc.json new file mode 100644 index 00000000..20befe60 --- /dev/null +++ b/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"] +} diff --git a/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-base1.json b/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-base1.json new file mode 100644 index 00000000..17acb7ca --- /dev/null +++ b/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 +} diff --git a/tsdoc-config/src/__tests__/assets/p6/tsconfig.json b/tsdoc-config/src/__tests__/assets/p6/tsconfig.json new file mode 100644 index 00000000..0967ef42 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p6/tsconfig.json @@ -0,0 +1 @@ +{} diff --git a/tsdoc-config/src/__tests__/assets/p6/tsdoc.json b/tsdoc-config/src/__tests__/assets/p6/tsdoc.json new file mode 100644 index 00000000..2a57f573 --- /dev/null +++ b/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 +} diff --git a/tsdoc/schemas/tsdoc.schema.json b/tsdoc/schemas/tsdoc.schema.json index 08c114b0..65cc7d9b 100644 --- a/tsdoc/schemas/tsdoc.schema.json +++ b/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", From 2e859ed36d6455136e10c41431415cc7e3f0d70a Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Thu, 21 Jan 2021 21:59:11 -0800 Subject: [PATCH 2/4] rush change --- .../octogonz-no-standard-tags_2021-01-22-05-59.json | 11 +++++++++++ .../octogonz-no-standard-tags_2021-01-22-05-59.json | 11 +++++++++++ 2 files changed, 22 insertions(+) create mode 100644 common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-05-59.json create mode 100644 common/changes/@microsoft/tsdoc/octogonz-no-standard-tags_2021-01-22-05-59.json diff --git a/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-05-59.json b/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-05-59.json new file mode 100644 index 00000000..a66fcff5 --- /dev/null +++ b/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-05-59.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc-config", + "comment": "Update tsdoc.json schema to add a new field \"noStandardTags\"", + "type": "minor" + } + ], + "packageName": "@microsoft/tsdoc-config", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file diff --git a/common/changes/@microsoft/tsdoc/octogonz-no-standard-tags_2021-01-22-05-59.json b/common/changes/@microsoft/tsdoc/octogonz-no-standard-tags_2021-01-22-05-59.json new file mode 100644 index 00000000..71f36ffc --- /dev/null +++ b/common/changes/@microsoft/tsdoc/octogonz-no-standard-tags_2021-01-22-05-59.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc", + "comment": "Update tsdoc.json schema to add a new field \"noStandardTags\"", + "type": "minor" + } + ], + "packageName": "@microsoft/tsdoc", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file From c14ad393a9465dbe268502f9e2790bdce1373eab Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Thu, 21 Jan 2021 22:01:11 -0800 Subject: [PATCH 3/4] rush change --- .../octogonz-no-standard-tags_2021-01-22-06-01.json | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-01.json diff --git a/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-01.json b/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-01.json new file mode 100644 index 00000000..be349c19 --- /dev/null +++ b/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-01.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc-config", + "comment": "TSDocConfigFile.configureParser() now clears any previous state, and it only defines standard tags if \"noStandardTags\" is not true.", + "type": "minor" + } + ], + "packageName": "@microsoft/tsdoc-config", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file From f1a96074f69eebdebd1bd7bc5c4e73e01a2351a2 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Thu, 21 Jan 2021 22:01:47 -0800 Subject: [PATCH 4/4] rush change --- .../octogonz-no-standard-tags_2021-01-22-06-02.json | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-02.json diff --git a/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-02.json b/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-02.json new file mode 100644 index 00000000..a0deae67 --- /dev/null +++ b/common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-02.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc-config", + "comment": "Added new API TSDocConfigFile.updateParser() which preserves the previous configuration state", + "type": "minor" + } + ], + "packageName": "@microsoft/tsdoc-config", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file