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..37b5f24c --- /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..27718108 --- /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 diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index 40a18430..19c4f473 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", @@ -409,6 +413,10 @@ test('Re-serialize p3 with defaults', () => { "syntaxKind": "block", "tagName": "@typeParam", }, + Object { + "syntaxKind": "block", + "tagName": "@version", + }, Object { "syntaxKind": "modifier", "tagName": "@virtual", @@ -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", 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..7dcd6698 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -415,6 +415,33 @@ export class StandardTags { standardization: Standardization.Extended }); + /** + * (Extended) + * + * Used to document the version number of the API on which the item was created. + * + * @remarks + * + * 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 + * /** + * * Fetches a book by its ISBN code. + * * @since 1.0.0 + * */ + * function fetchBookByIsbn(isbnCode: string): Book; + * ``` + * + * 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', + syntaxKind: TSDocTagSyntaxKind.BlockTag, + standardization: Standardization.Extended + }); + /** * (Extended) * @@ -467,6 +494,33 @@ 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, it can contain as much text as you want, however 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 on which the item was 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 +564,10 @@ export class StandardTags { StandardTags.returns, StandardTags.sealed, StandardTags.see, + StandardTags.since, StandardTags.throws, StandardTags.typeParam, + StandardTags.version, StandardTags.virtual ];