Skip to content

Commit f18225c

Browse files
octogonzoctogonz
authored
Merge pull request #279 from microsoft/octogonz/no-standard-tags
Add a new tsdoc.json setting "noStandardTags"
2 parents 9befb8b + f1a9607 commit f18225c

14 files changed

+178
-4
lines changed

‎common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-05-59.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/tsdoc-config",
5+
"comment": "Update tsdoc.json schema to add a new field \"noStandardTags\"",
6+
"type": "minor"
7+
}
8+
],
9+
"packageName": "@microsoft/tsdoc-config",
10+
"email": "4673363+octogonz@users.noreply.github.com"
11+
}

‎common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-01.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/tsdoc-config",
5+
"comment": "TSDocConfigFile.configureParser() now clears any previous state, and it only defines standard tags if \"noStandardTags\" is not true.",
6+
"type": "minor"
7+
}
8+
],
9+
"packageName": "@microsoft/tsdoc-config",
10+
"email": "4673363+octogonz@users.noreply.github.com"
11+
}

‎common/changes/@microsoft/tsdoc-config/octogonz-no-standard-tags_2021-01-22-06-02.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/tsdoc-config",
5+
"comment": "Added new API TSDocConfigFile.updateParser() which preserves the previous configuration state",
6+
"type": "minor"
7+
}
8+
],
9+
"packageName": "@microsoft/tsdoc-config",
10+
"email": "4673363+octogonz@users.noreply.github.com"
11+
}

‎common/changes/@microsoft/tsdoc/octogonz-no-standard-tags_2021-01-22-05-59.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/tsdoc",
5+
"comment": "Update tsdoc.json schema to add a new field \"noStandardTags\"",
6+
"type": "minor"
7+
}
8+
],
9+
"packageName": "@microsoft/tsdoc",
10+
"email": "4673363+octogonz@users.noreply.github.com"
11+
}

‎tsdoc-config/src/TSDocConfigFile.ts

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ interface ITagConfigJson {
3838
interface IConfigJson {
3939
$schema: string;
4040
extends?: string[];
41+
noStandardTags?: boolean;
4142
tagDefinitions?: ITagConfigJson[];
4243
supportForTags?: { [tagName: string]: boolean };
4344
}
@@ -64,6 +65,7 @@ export class TSDocConfigFile {
6465
private _hasErrors: boolean;
6566
private _tsdocSchema: string;
6667
private readonly _extendsPaths: string[];
68+
private _noStandardTags: boolean | undefined;
6769
private readonly _tagDefinitions: TSDocTagDefinition[];
6870
private readonly _tagDefinitionNames: Set<string>;
6971
private readonly _supportForTags: Map<string, boolean>;
@@ -78,6 +80,7 @@ export class TSDocConfigFile {
7880
this._fileMTime = 0;
7981
this._tsdocSchema = '';
8082
this._extendsPaths = [];
83+
this._noStandardTags = undefined;
8184
this._tagDefinitions = [];
8285
this._tagDefinitionNames = new Set();
8386
this._supportForTags = new Map();
@@ -133,6 +136,25 @@ export class TSDocConfigFile {
133136
return this._extendsPaths;
134137
}
135138

139+
/**
140+
* By default, the config file loader will predefine all of the standardized TSDoc tags. To disable this and
141+
* start with a completely empty configuration, set `noStandardTags` to true.
142+
*
143+
* @remarks
144+
* If a config file uses `"extends"` to include settings from base config files, then its setting will
145+
* override any settings from the base config files. If `"noStandardTags"` is not specified, then this
146+
* property will be `undefined`. The config files are applied in the order they are processed (a depth-first
147+
* traversal of the `"extends"` references), and files processed later can override earlier files.
148+
* If no config file specifies `noStandardTags` then the default value is `false`.
149+
*/
150+
public get noStandardTags(): boolean | undefined {
151+
return this._noStandardTags;
152+
}
153+
154+
public set noStandardTags(value: boolean | undefined) {
155+
this._noStandardTags = value;
156+
}
157+
136158
public get tagDefinitions(): ReadonlyArray<TSDocTagDefinition> {
137159
return this._tagDefinitions;
138160
}
@@ -288,6 +310,8 @@ export class TSDocConfigFile {
288310
this._extendsPaths.push(...configJson.extends);
289311
}
290312

313+
this.noStandardTags = configJson.noStandardTags;
314+
291315
for (const jsonTagDefinition of configJson.tagDefinitions || []) {
292316
let syntaxKind: TSDocTagSyntaxKind;
293317
switch (jsonTagDefinition.syntaxKind) {
@@ -444,6 +468,10 @@ export class TSDocConfigFile {
444468
public static loadFromParser(configuration: TSDocConfiguration): TSDocConfigFile {
445469
const configFile: TSDocConfigFile = new TSDocConfigFile();
446470

471+
// The standard tags will be mixed together with custom definitions,
472+
// so set noStandardTags=true to avoid defining them twice.
473+
configFile.noStandardTags = true;
474+
447475
for (const tagDefinition of configuration.tagDefinitions) {
448476
configFile.addTagDefinition({
449477
syntaxKind: tagDefinition.syntaxKind,
@@ -476,6 +504,10 @@ export class TSDocConfigFile {
476504
$schema: TSDocConfigFile.CURRENT_SCHEMA_URL,
477505
};
478506

507+
if (this.noStandardTags !== undefined) {
508+
configJson.noStandardTags = this.noStandardTags;
509+
}
510+
479511
if (this.tagDefinitions.length > 0) {
480512
configJson.tagDefinitions = [];
481513
for (const tagDefinition of this.tagDefinitions) {
@@ -551,9 +583,24 @@ export class TSDocConfigFile {
551583
* Any `extendsFile` settings will also applied.
552584
*/
553585
public configureParser(configuration: TSDocConfiguration): void {
586+
if (this._getNoStandardTagsWithExtends()) {
587+
// Do not define standard tags
588+
configuration.clear(true);
589+
} else {
590+
// Define standard tags (the default behavior)
591+
configuration.clear(false);
592+
}
593+
594+
this.updateParser(configuration);
595+
}
596+
597+
/**
598+
* This is the same as {@link configureParser}, but it preserves any previous state.
599+
*/
600+
public updateParser(configuration: TSDocConfiguration): void {
554601
// First apply the base config files
555602
for (const extendsFile of this.extendsFiles) {
556-
extendsFile.configureParser(configuration);
603+
extendsFile.updateParser(configuration);
557604
}
558605

559606
// Then apply this one
@@ -575,4 +622,26 @@ export class TSDocConfigFile {
575622
}
576623
});
577624
}
625+
626+
private _getNoStandardTagsWithExtends(): boolean {
627+
if (this.noStandardTags !== undefined) {
628+
return this.noStandardTags;
629+
}
630+
631+
// This config file does not specify "noStandardTags", so consider any base files referenced using "extends"
632+
let result: boolean | undefined = undefined;
633+
for (const extendsFile of this.extendsFiles) {
634+
const extendedValue: boolean | undefined = extendsFile._getNoStandardTagsWithExtends();
635+
if (extendedValue !== undefined) {
636+
result = extendedValue;
637+
}
638+
}
639+
640+
if (result === undefined) {
641+
// If no config file specifies noStandardTags, then it defaults to false
642+
result = false;
643+
}
644+
645+
return result;
646+
}
578647
}

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

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ expect.addSnapshotSerializer({
2121
fileNotFound: configFile.fileNotFound,
2222
extendsPaths: configFile.extendsPaths,
2323
extendsFiles: configFile.extendsFiles,
24+
noStandardTags: configFile.noStandardTags,
2425
tagDefinitions: configFile.tagDefinitions,
2526
supportForTags: Array.from(configFile.supportForTags).map(([tagName, supported]) => ({ tagName, supported })),
2627
messages: configFile.log.messages,
@@ -40,6 +41,7 @@ test('Load p1', () => {
4041
"fileNotFound": false,
4142
"filePath": "assets/p1/tsdoc.json",
4243
"messages": Array [],
44+
"noStandardTags": undefined,
4345
"supportForTags": Array [],
4446
"tagDefinitions": Array [],
4547
"tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
@@ -68,6 +70,7 @@ test('Load p2', () => {
6870
"unformattedText": "File not found",
6971
},
7072
],
73+
"noStandardTags": undefined,
7174
"supportForTags": Array [],
7275
"tagDefinitions": Array [],
7376
"tsdocSchema": "",
@@ -85,6 +88,7 @@ test('Load p3', () => {
8588
"fileNotFound": false,
8689
"filePath": "assets/p3/base1/tsdoc-base1.json",
8790
"messages": Array [],
91+
"noStandardTags": undefined,
8892
"supportForTags": Array [
8993
Object {
9094
"supported": true,
@@ -108,6 +112,7 @@ test('Load p3', () => {
108112
"fileNotFound": false,
109113
"filePath": "assets/p3/base2/tsdoc-base2.json",
110114
"messages": Array [],
115+
"noStandardTags": undefined,
111116
"supportForTags": Array [
112117
Object {
113118
"supported": false,
@@ -133,6 +138,7 @@ test('Load p3', () => {
133138
"fileNotFound": false,
134139
"filePath": "assets/p3/tsdoc.json",
135140
"messages": Array [],
141+
"noStandardTags": undefined,
136142
"supportForTags": Array [
137143
Object {
138144
"supported": true,
@@ -163,6 +169,7 @@ test('Load p4', () => {
163169
"fileNotFound": false,
164170
"filePath": "assets/p4/node_modules/example-lib/dist/tsdoc-example.json",
165171
"messages": Array [],
172+
"noStandardTags": undefined,
166173
"supportForTags": Array [],
167174
"tagDefinitions": Array [
168175
TSDocTagDefinition {
@@ -182,6 +189,7 @@ test('Load p4', () => {
182189
"fileNotFound": false,
183190
"filePath": "assets/p4/tsdoc.json",
184191
"messages": Array [],
192+
"noStandardTags": undefined,
185193
"supportForTags": Array [],
186194
"tagDefinitions": Array [
187195
TSDocTagDefinition {
@@ -197,7 +205,7 @@ test('Load p4', () => {
197205
`);
198206
});
199207

200-
test('Re-serialize p2', () => {
208+
test('Re-serialize p3', () => {
201209
const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p3'));
202210
// This is the data from p3/tsdoc.json, ignoring its "extends" field.
203211
expect(configFile.saveToObject()).toMatchInlineSnapshot(`
@@ -216,7 +224,7 @@ test('Re-serialize p2', () => {
216224
`);
217225
});
218226

219-
test('Re-serialize p2 without defaults', () => {
227+
test('Re-serialize p3 without defaults', () => {
220228
const parserConfiguration: TSDocConfiguration = new TSDocConfiguration();
221229
parserConfiguration.clear(true);
222230

@@ -225,10 +233,12 @@ test('Re-serialize p2 without defaults', () => {
225233
expect(defaultsConfigFile.saveToObject()).toMatchInlineSnapshot(`
226234
Object {
227235
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
236+
"noStandardTags": true,
228237
}
229238
`);
230239

231240
const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p3'));
241+
configFile.noStandardTags = true;
232242
configFile.configureParser(parserConfiguration);
233243

234244
const mergedConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromParser(parserConfiguration);
@@ -238,6 +248,7 @@ test('Re-serialize p2 without defaults', () => {
238248
expect(mergedConfigFile.saveToObject()).toMatchInlineSnapshot(`
239249
Object {
240250
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
251+
"noStandardTags": true,
241252
"supportForTags": Object {
242253
"@base1": true,
243254
"@base2": true,
@@ -260,14 +271,15 @@ test('Re-serialize p2 without defaults', () => {
260271
`);
261272
});
262273

263-
test('Re-serialize p2 with defaults', () => {
274+
test('Re-serialize p3 with defaults', () => {
264275
const parserConfiguration: TSDocConfiguration = new TSDocConfiguration();
265276

266277
const defaultsConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromParser(parserConfiguration);
267278
// This is the default configuration created by the TSDocConfigFile constructor.
268279
expect(defaultsConfigFile.saveToObject()).toMatchInlineSnapshot(`
269280
Object {
270281
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
282+
"noStandardTags": true,
271283
"tagDefinitions": Array [
272284
Object {
273285
"syntaxKind": "modifier",
@@ -389,6 +401,7 @@ test('Re-serialize p2 with defaults', () => {
389401
expect(mergedConfigFile.saveToObject()).toMatchInlineSnapshot(`
390402
Object {
391403
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
404+
"noStandardTags": true,
392405
"supportForTags": Object {
393406
"@base1": true,
394407
"@base2": true,
@@ -516,3 +529,23 @@ test('Re-serialize p2 with defaults', () => {
516529
}
517530
`);
518531
});
532+
533+
test('Test noStandardTags for p5', () => {
534+
const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p5'));
535+
536+
const configuration: TSDocConfiguration = new TSDocConfiguration();
537+
configFile.configureParser(configuration);
538+
539+
// noStandardTags=true because tsdoc-base2.json overrides tsdoc-base1.json, and tsdoc.json is undefined
540+
expect(configuration.tagDefinitions.length).toEqual(0);
541+
});
542+
543+
test('Test noStandardTags for p6', () => {
544+
const configFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.join(__dirname, 'assets/p6'));
545+
546+
const configuration: TSDocConfiguration = new TSDocConfiguration();
547+
configFile.configureParser(configuration);
548+
549+
// noStandardTags=false because tsdoc.json overrides tsdoc-base1.json
550+
expect(configuration.tagDefinitions.length).toBeGreaterThan(0);
551+
});

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
3+
"noStandardTags": false
4+
}

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
3+
"noStandardTags": true
4+
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{}

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
3+
"extends": ["./base1/tsdoc-base1.json", "./base2/tsdoc-base2.json"]
4+
}

0 commit comments

Comments
 (0)