Open rbuckton opened 4 years ago
I'd prefer to simply remove the old syntax and got "all in" on the new syntax. We technically have this freedom, as we haven't published the version 1.0.0
of the parser library yet. We've been reasonably clear that the spec is still evolving.
To smooth the transition, I suspect that if we temporarily accepted both #
and !
as the the package delimiter, most of the old references would continue to parse correctly. At least, in the code bases I'm familiar with, the number of member selectors using (
:
)
is small enough that it could be fixed up relatively quickly.
Keep in mind that API Extractor will most likely allow MyClass.myMember
as a synonym for MyClass#myMember:member
in cases where there is no ambiguous static member using that name. (I'm fairly convinced that the #
vs .
distinction is too abstruse to inflict on casual users heheh.)
Maybe over the holiday I can see about implementing this. It really should be our top priority for enhancements to TSDoc.
How would you propose doing this? Replacing DocDeclarationReference
in DocLinkTag
with DocDeclarationReference | DeclarationReference
, or having DocDeclarationReference
store a DeclarationReference
as an alternative to packageName
/importPath
/memberReferences
?
There is still an ambiguity with #
between the old and new formats. foo#bar
in the previous format would be a package named foo
with an export named bar
, but in the new format its a type named foo
with a non-static member named bar
.
How would you propose doing this? Replacing
DocDeclarationReference
inDocLinkTag
withDocDeclarationReference | DeclarationReference
, or havingDocDeclarationReference
store aDeclarationReference
as an alternative topackageName
/importPath
/memberReferences
?
No, I'm thinking we could redesign DocDeclarationReference
, DocMemberReference
, DocMemberSelector
, etc to represent your new syntax.
I don't think we can use the DeclarationReference
as-is. Its nodes would be inconsistent with the rest of the AST. For example, they do not track a DocExcerpt
, which is needed for syntax highlighting. Also it has a separate tokenizer, and its error messages are thrown as exceptions, rather than being reported with a TSDocMessageId
and token sequence.
If you have projects that are using the DeclarationReference
API directly, it would be a good idea to call out any additional requirements. Ideally we'd want to improve the TSDoc parser to implement these requirements, so we have a single solution for declaration references and the full TSDoc grammar.
There is still an ambiguity with
#
between the old and new formats.foo#bar
in the previous format would be a package namedfoo
with an export namedbar
, but in the new format its a type namedfoo
with a non-static member namedbar
.
Yeah, you are right. 🤔 Hmm... If it really is important to provide backwards compatibility for the old syntax (which I'm not sure we do), maybe we could provide a configuration option to opt-in or opt-out of the new syntax. It could be specified in tsdoc.json
so the ESLint plugin will validate it correctly.
(Or, it might be okay to go all-in on the new syntax. The current library has been stable for a while, so perhaps people could reasonably defer upgrading until they are ready.)
It seems that the parser (playground) and eslint-plugin-tsdoc doesn't accept the !
delimiter at all?
The current TSDoc declaration reference syntax differs from the new proposed declaration reference syntax. I would propose the following additional syntax for
{@link}
and related tags as a means opt-in to the new proposed declaration reference syntax:For example: