From 5ffc2d1e7f8c25ddbf4499368d1b10952cf14327 Mon Sep 17 00:00:00 2001 From: Lucas Bastian <49524093+Ratibus11@users.noreply.github.com> Date: Wed, 10 Apr 2024 10:52:58 +0200 Subject: [PATCH 1/6] Adding since / version tags definition --- tsdoc/etc/tsdoc.api.md | 2 ++ tsdoc/src/details/StandardTags.ts | 54 +++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/tsdoc/etc/tsdoc.api.md b/tsdoc/etc/tsdoc.api.md index d21fb58d..445b2ffe 100644 --- a/tsdoc/etc/tsdoc.api.md +++ b/tsdoc/etc/tsdoc.api.md @@ -1150,8 +1150,10 @@ export class StandardTags { static readonly returns: TSDocTagDefinition; static readonly sealed: TSDocTagDefinition; static readonly see: TSDocTagDefinition; + static readonly since: TSDocTagDefinition; static readonly throws: TSDocTagDefinition; static readonly typeParam: TSDocTagDefinition; + static readonly version: TSDocTagDefinition; static readonly virtual: TSDocTagDefinition; } diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index 67706e4d..cfa5e880 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -415,6 +415,32 @@ export class StandardTags { standardization: Standardization.Extended }); + /** + * (Extended) + * + * Used to document the version number of the API since which the item has been created. + * + * @remarks + * + * Even if this tag is a block, so it can contain as much text as you want, it is recommended to use only the version number. + * + * For example: + * ```ts + * /** + * * Fetches a book by its ISBN code. + * * @since 1.0.0 + * */ + * function fetchBookByIsbn(isbnCode: string): Book; + * ``` + * + * This function has been created since version 1.0.0. This tag mustn't be changed in the future, even if the function is updated. In this case the `@version` tag should be used/updated instead. + */ + public static readonly since: TSDocTagDefinition = StandardTags._defineTag({ + tagName: '@since', + syntaxKind: TSDocTagSyntaxKind.BlockTag, + standardization: Standardization.Extended + }); + /** * (Extended) * @@ -467,6 +493,32 @@ export class StandardTags { standardization: Standardization.Core }); + /** + * (Extended) + * + * Used to document the version number of the API item. + * + * @remarks + * + * Even if this tag is a block, so it can contain as much text as you want, it is recommended to use only the version number. + * + * For example: + * ```ts + * /** + * * Fetches a book by its ISBN code. + * * @version 1.0.0 + * */ + * function fetchBookByIsbn(isbnCode: string): Book; + * ``` + * + * This function version is currently 1.0.0. This tag must be updated every time the function is updated. If you want to document the version of the API since which the item has been created, the `@since` tag should be used instead. + */ + public static readonly version: TSDocTagDefinition = StandardTags._defineTag({ + tagName: '@version', + syntaxKind: TSDocTagSyntaxKind.BlockTag, + standardization: Standardization.Extended + }); + /** * (Extended) * @@ -510,8 +562,10 @@ export class StandardTags { StandardTags.returns, StandardTags.sealed, StandardTags.see, + StandardTags.since, StandardTags.throws, StandardTags.typeParam, + StandardTags.version, StandardTags.virtual ]; From 2b63216797d06ad41604b86463635adef295b7d7 Mon Sep 17 00:00:00 2001 From: Lucas Bastian <49524093+Ratibus11@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:04:19 +0200 Subject: [PATCH 2/6] Fixing tests TSDocConfigFile --- .../src/__tests__/TSDocConfigFile.test.ts | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index 40a18430..7184b938 100644 --- a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts +++ b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts @@ -399,6 +399,10 @@ test('Re-serialize p3 with defaults', () => { "syntaxKind": "block", "tagName": "@see", }, + Object { + "syntaxKind": "block", + "tagName": "@since" + }, Object { "allowMultiple": true, "syntaxKind": "block", @@ -413,6 +417,10 @@ test('Re-serialize p3 with defaults', () => { "syntaxKind": "modifier", "tagName": "@virtual", }, + Object { + "syntaxKind": "block", + "tagName": "@version", + }, ], } `); @@ -527,6 +535,10 @@ test('Re-serialize p3 with defaults', () => { "syntaxKind": "block", "tagName": "@see", }, + Object { + syntaxKind: "block", + tagName: "@since", + }, Object { "allowMultiple": true, "syntaxKind": "block", @@ -537,6 +549,10 @@ test('Re-serialize p3 with defaults', () => { "syntaxKind": "block", "tagName": "@typeParam", }, + Object { + syntaxKind: "block", + tagName: "@version", + }, Object { "syntaxKind": "modifier", "tagName": "@virtual", From 51fe8357470251bad19a0f06265206b06ee15ac9 Mon Sep 17 00:00:00 2001 From: Lucas Bastian <49524093+Ratibus11@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:15:44 +0200 Subject: [PATCH 3/6] rush build completed --- .../src/__tests__/TSDocConfigFile.test.ts | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index 7184b938..19c4f473 100644 --- a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts +++ b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts @@ -401,7 +401,7 @@ test('Re-serialize p3 with defaults', () => { }, Object { "syntaxKind": "block", - "tagName": "@since" + "tagName": "@since", }, Object { "allowMultiple": true, @@ -413,14 +413,14 @@ test('Re-serialize p3 with defaults', () => { "syntaxKind": "block", "tagName": "@typeParam", }, - Object { - "syntaxKind": "modifier", - "tagName": "@virtual", - }, Object { "syntaxKind": "block", "tagName": "@version", }, + Object { + "syntaxKind": "modifier", + "tagName": "@virtual", + }, ], } `); @@ -536,8 +536,8 @@ test('Re-serialize p3 with defaults', () => { "tagName": "@see", }, Object { - syntaxKind: "block", - tagName: "@since", + "syntaxKind": "block", + "tagName": "@since", }, Object { "allowMultiple": true, @@ -550,8 +550,8 @@ test('Re-serialize p3 with defaults', () => { "tagName": "@typeParam", }, Object { - syntaxKind: "block", - tagName: "@version", + "syntaxKind": "block", + "tagName": "@version", }, Object { "syntaxKind": "modifier", From dfcc7bad98da45a38d7d1565423492fe0936f9e9 Mon Sep 17 00:00:00 2001 From: Lucas Bastian <49524093+Ratibus11@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:36:19 +0200 Subject: [PATCH 4/6] Add changes to 'rush change' --- .../@microsoft/tsdoc-config/main_2024-04-10-09-34.json | 10 ++++++++++ .../@microsoft/tsdoc/main_2024-04-10-09-34.json | 10 ++++++++++ 2 files changed, 20 insertions(+) create mode 100644 common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json create mode 100644 common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json diff --git a/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json b/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json new file mode 100644 index 00000000..1374e7c6 --- /dev/null +++ b/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc-config", + "comment": "Adding support for '@since' and '@version' tags", + "type": "minor" + } + ], + "packageName": "@microsoft/tsdoc-config" +} \ No newline at end of file diff --git a/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json b/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json new file mode 100644 index 00000000..d7fb016f --- /dev/null +++ b/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc", + "comment": "Adding support for '@since' and '@version' tags", + "type": "minor" + } + ], + "packageName": "@microsoft/tsdoc" +} \ No newline at end of file From f20c9cb489d14e51133882d915f5053cb88216e8 Mon Sep 17 00:00:00 2001 From: Lucas Bastian <49524093+Ratibus11@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:43:18 +0200 Subject: [PATCH 5/6] Fix tags description --- tsdoc/src/details/StandardTags.ts | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index cfa5e880..7dcd6698 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -418,11 +418,11 @@ export class StandardTags { /** * (Extended) * - * Used to document the version number of the API since which the item has been created. + * Used to document the version number of the API on which the item was created. * * @remarks * - * Even if this tag is a block, so it can contain as much text as you want, it is recommended to use only the version number. + * Even if this tag is a block, it can contain as much text as you want, however it is recommended to use only the version number. * * For example: * ```ts @@ -433,7 +433,8 @@ export class StandardTags { * function fetchBookByIsbn(isbnCode: string): Book; * ``` * - * This function has been created since version 1.0.0. This tag mustn't be changed in the future, even if the function is updated. In this case the `@version` tag should be used/updated instead. + * This function has been created on version 1.0.0. This tag must not be changed in the future, even if the function is updated. + * In this case the `@version` tag should be used/updated instead. */ public static readonly since: TSDocTagDefinition = StandardTags._defineTag({ tagName: '@since', @@ -500,7 +501,7 @@ export class StandardTags { * * @remarks * - * Even if this tag is a block, so it can contain as much text as you want, it is recommended to use only the version number. + * Even if this tag is a block, it can contain as much text as you want, however it is recommended to use only the version number. * * For example: * ```ts @@ -511,7 +512,8 @@ export class StandardTags { * function fetchBookByIsbn(isbnCode: string): Book; * ``` * - * This function version is currently 1.0.0. This tag must be updated every time the function is updated. If you want to document the version of the API since which the item has been created, the `@since` tag should be used instead. + * This function version is currently 1.0.0. This tag must be updated every time the function is updated. + * If you want to document the version of the API on which the item was created, the `@since` tag should be used instead. */ public static readonly version: TSDocTagDefinition = StandardTags._defineTag({ tagName: '@version', From e30300c1d62f0844cdf8b261a7fd312cce2932cc Mon Sep 17 00:00:00 2001 From: Lucas Bastian <49524093+Ratibus11@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:46:53 +0200 Subject: [PATCH 6/6] Change changelog comment --- .../changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json | 2 +- common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json b/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json index 1374e7c6..37b5f24c 100644 --- a/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json +++ b/common/changes/@microsoft/tsdoc-config/main_2024-04-10-09-34.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@microsoft/tsdoc-config", - "comment": "Adding support for '@since' and '@version' tags", + "comment": "Adding support for `@since` and `@version` tags", "type": "minor" } ], diff --git a/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json b/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json index d7fb016f..27718108 100644 --- a/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json +++ b/common/changes/@microsoft/tsdoc/main_2024-04-10-09-34.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@microsoft/tsdoc", - "comment": "Adding support for '@since' and '@version' tags", + "comment": "Adding support for `@since` and `@version` tags", "type": "minor" } ],