From de625b3045ebc81f10b3444a6d48301d2074f673 Mon Sep 17 00:00:00 2001
From: Zendy <50132805+zendy199x@users.noreply.github.com>
Date: Fri, 27 Mar 2026 11:01:01 +0700
Subject: [PATCH] feat: implement new `{@link {beta-declaration-reference}}`
 syntax

The TSDoc parser needs to be updated to support a new syntax for the `{@link}` tag, allowing users to opt into a "beta declaration reference format." This new format uses double curly braces `{{...}}` to enclose the reference, and a `!` character as a separator for package names, aligning with a proposed standard. This enhancement improves interoperability and future-proofs TSDoc's declaration reference capabilities without breaking existing syntax.

Signed-off-by: Zendy <50132805+zendy199x@users.noreply.github.com>
---
 tsdoc/src/parser/TSDocParser.ts | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tsdoc/src/parser/TSDocParser.ts b/tsdoc/src/parser/TSDocParser.ts
index 226bec72..96d824fd 100644
--- a/tsdoc/src/parser/TSDocParser.ts
+++ b/tsdoc/src/parser/TSDocParser.ts
@@ -26,6 +26,24 @@ export class TSDocParser {
     }
   }
 
+  /**
+   * Creates a TSDocParser instance that supports the beta declaration reference format.
+   * This format uses double curly braces `{{...}}` to enclose the reference, and a `!` character
+   * as a separator for package names.
+   *
+   * @remarks
+   * This is an opt-in feature. By default, the TSDocParser does not support this beta syntax.
+   * The returned parser instance will have its {@link TSDocParser.configuration}
+   * pre-configured to recognize the beta declaration reference syntax.
+   */
+  public static createWithBetaDeclarationReferences(): TSDocParser {
+    const configuration: TSDocConfiguration = new TSDocConfiguration();
+    // This method (assumed to exist in TSDocConfiguration) would internally modify
+    // the parsing rules for declaration references to recognize the beta syntax.
+    configuration.configureForBetaDeclarationReferences();
+    return new TSDocParser(configuration);
+  }
+
   public parseString(text: string): ParserContext {
     return this.parseRange(TextRange.fromString(text));
   }