Add unqualified JSDoc member references #44202
Conversation
This allows unqualified references like:
```ts
class Zero {
/** @param buddy Must be {@link D_HORSE} or {@link D_DOG}. */
deploy(buddy: number) { }
static D_HORSE = 1
static D_DOG = 2
}
```
I surveyed @see and @link again to estimate how common this is. I found
a little over 200 uses, which is around 2%. Sorted by frequency, this
*is* the next feature on the list, along with the `module:` prefix.
So I think this is about the right point to stop adding code.
In this case, however, I liked most of the uses -- there were a lot
of deprecated functions that referenced a function just below, where it
would be wordy to qualify the name, but the reader would benefit from a
link.
Note that unqualified references do *not* work inside type or object
literals. The code I ended up with is quite complicated and I didn't
observe any uses in the wild.
Fixes #43595
typescript-bot
added
Author: Team
For Milestone Bug
Since they don't work anyway
sandersn
requested review from
andrewbranch,
amcasey,
DanielRosenwasser and
elibarzilay
|
Is my understanding correct? class C {
m() {}
n() {
type T = {
m: number;
/** {@link m} <- this refers to C.m? */
n: number;
}
}
} |
|
I could have sworn there was a |
|
@typescript-bot pack this |
|
@amcasey Your interpretation is correct, because an unresolved identifier in jsdoc looks for an ancestor like so: |
|
Hey @sandersn, I've packed this into an installable tgz. You can install it for testing by referencing it in your and then running There is also a playground for this build and an npm module you can use via |
|
@sandersn I can’t tell if your response means to imply that it’s already working how you think it should work or not, but I think my intuition is that if we will look up unqualified member names in classes and interfaces, we should also do so in type literals and object literals, especially since the latter can be difficult to name otherwise: (function() {
return {
/** {@link b} If this doesn't resolve, what's the alternative? */
a() {},
b() {}
})();I’m not claiming that it is important that this works, but wanted to understand your thinking on it. I guess the tradeoff with resolving more unqualified things is that you could unexpectedly shadow something in a higher scope, and become unable to link to it. |
|
Right, I wasn't clear about my intentions: As the PR stands today, I intended for classes and interfaces to support unqualified references and type and object literals not to support them. That's because
Note that (1) and (4) apply to existing code, but we're going to change future code by shipping this feature. So it might become more important later. (3) might also change since I'll take another look at (2) when I have the chance, although it's going to be a little slow since I'm on DT this week and got started on another JS experiment. |
|
You've addressed my concerns. |
This allows unqualified references like:
I surveyed @see and @link again to estimate how common this is. I found a little over 200 uses, which is around 2%. [1] Sorted by frequency, this
is the next feature on the list, along with the
module:prefix. So I think this is about the right point to stop adding features.In this case, however, I liked most of the uses -- there were a lot of deprecated functions that referenced a function just below, where it would be wordy to qualify the name, but the reader would benefit from a link.
Note that unqualified references do not work inside type or object literals. The code I ended up with is quite complicated and I didn't observe any uses in the wild.
Fixes #43595
[1] The survey code was a hand-written approximation of member resolution, so it probably missed some uses.