feat: implement new {@link {beta-declaration-reference}} syntax#469
feat: implement new {@link {beta-declaration-reference}} syntax#469zendy199x wants to merge 1 commit intomicrosoft:mainfrom
{@link {beta-declaration-reference}} syntax#469Conversation
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>
zendy199x
requested review from
apostolisms,
bmiddha,
dmichon-msft,
iclanton,
jxanthony and
octogonz
as code owners
There was a problem hiding this comment.
Pull request overview
This PR aims to add opt-in support in the TSDoc parser for a new {@link {beta-declaration-reference}} syntax that uses {...} (appearing as {{...}} inside the inline tag) and ! as the package separator.
Changes:
- Added a new
TSDocParser.createWithBetaDeclarationReferences()factory intended to return a parser configured for the beta declaration reference syntax.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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); | ||
| } |
There was a problem hiding this comment.
This introduces a new public API surface (createWithBetaDeclarationReferences) but there are no tests exercising it. Please add parser tests covering at least the examples from #202 (e.g., {@link {package!MyClass}}, {@link {Merged:interface}}, and the | link text form) to ensure the opt-in behavior works and doesn’t regress existing @link parsing.
| 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); | ||
| } | ||
|
|
There was a problem hiding this comment.
configureForBetaDeclarationReferences() is not defined on TSDocConfiguration (no such method exists in tsdoc/src/configuration/TSDocConfiguration.ts), so this new factory will not compile. Either add the configuration API and its implementation (and include it in this PR), or remove this call and implement beta parsing via an existing/introduced configuration flag.
| 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); | |
| } | |
| return new 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); | ||
| } |
There was a problem hiding this comment.
The PR description/issue call for parsing support for {@link {…}} beta declaration references, but this change only adds a factory method and does not modify the actual parsing logic (e.g., NodeParser._parseLinkTagCodeDestination() / _parseDeclarationReference()) to recognize {...} destinations or the ! package separator. As written, opting in via this method will not change behavior even if the configuration call existed.
Summary
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.Changes
tsdoc/src/parser/TSDocParser.tsThe 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.Testing
Closes #202