Add support for @since and @version tags

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"
+}

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"
+}

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",

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;
 }
 

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
   ];