Treat link tag as comment #25206
Treat link tag as comment #25206
Conversation
But my machine is dying, so this is an emergency commit.
But it's not right yet; the test I added fails. See the TODO I added.
| case SyntaxKind.OpenBraceToken: | ||
| state = JSDocState.SavingComments; | ||
| if (lookAhead(() => nextJSDocToken() === SyntaxKind.AtToken && tokenIsIdentifierOrKeyword(nextJSDocToken()) && scanner.getTokenText() === "link")) { | ||
| pushComment(scanner.getTokenText()); |
There was a problem hiding this comment.
Does this handle {@link} (malformed tag) well?
There was a problem hiding this comment.
It's basically a skip, so any sequence of {@link is handled correctly. It doesn't handle the unbraced @link ... or the extra space in { @link, neither of which are legal jsdoc, but could occur.
There was a problem hiding this comment.
After thinking about it a bit more:
- unbraced
@linkis formatted like a top-level tag, so I think it's fine to treat it as one. - skipping arbitrary whitespace between
{and@linkis a lot of work with the current tokeniser. We should switch to the normal tokeniser and then revisit this code.
There was a problem hiding this comment.
So only tags named "link" has this special behavior ? Isn't this kind of arbitrary and unexpected behavior? Reminds me something I heard about an old windows version having a code like if(process.name==='the sims'){increaseSomething()}.
What's the reason for this? Is it for IDEs trying to support link in JavaScript projects ? Is it really important to hack the parser like this so one or two IDEs have an easy way of locating the parent tag description and position to insert a link ? They can still implement that (although it's harder/hacky/slow for them) without this hack in the compiler...
In which kind of projects are they trying to support @type ? Which reference syntax are these projects using , the usejsdocs.org one or TypeScript one?
In the later case, these projects are already breaking usejsdocs "standard" so they should not be using @link or {@link} but something else
In the first case, then I assume the motive for this hack is to support IDEs so they can easily/fast recreate the broken parent tag description and find the position to insert the anchor. If that's the case don't you think they should be responsible of solving their own problems? And if, as best case, they are just trying to solve the problem of jsdoc referencing once and for all, do you think this is the correct way of doing it?
If this is more or less right, then I'm worried that you didn't consider nor the compiler API user (for which BTW you introduced a breaking change), nor in the jsdoc writer for which TypeScript could provide typechecked references supporting refactors easily, and nor on typeScript developers since althoguh this change affected compiler performance minimally it shows performance place in this project priorities
I made an informal quick proposal #16498 (comment) and I would love to document in more detail discuss and implement it, but I would like first to know if such feature would be accepted ?
I think TypeScript now has the opportunity to define the definitely and single way of document JavaScript APIs as other languages have, and a feature like this would help a lot in that direction.
Don't take me wrong, I admire this project's contributors , but this just surprise me, sorry for the long comment, thanks.
There was a problem hiding this comment.
was The Sims part of the Windows spec? In this case @link is part of jsdoc that Typescript explicitly wants to opt out of. And it's the only non-top-level tag in jsdoc, which means that code to support it (or skip it) will look special.
After some discussion we decided that the best approach for the
@linktag is stop trying to parse it at all. This PR parses it as a comment instead. This trivially makes@linkinline, but it's no longer a tag.Of course, there is no name resolution capability as requested in #16498. However, it does make the quick info formatting correct (as desired in a recent spate of PRs on Definitely Typed [1]), and lets VS code apply its own formatting as much as possible.
[1] DefinitelyTyped/DefinitelyTyped#26674
DefinitelyTyped/DefinitelyTyped#26524
DefinitelyTyped/DefinitelyTyped#26452
DefinitelyTyped/DefinitelyTyped#26449