Skip to content

@link and @see should lookup sibling methods/properties without a class prefix #43595

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Closed
sandersn opened this issue Apr 8, 2021 · 1 comment · Fixed by #44202
Closed

@link and @see should lookup sibling methods/properties without a class prefix #43595

sandersn opened this issue Apr 8, 2021 · 1 comment · Fixed by #44202
Assignees
Labels
Experience Enhancement Noncontroversial enhancements Fix Available A PR has been opened for this issue
Milestone

Comments

@sandersn
Copy link
Member

sandersn commented Apr 8, 2021

class C {
    m() { }
    /** {@link m} */
    p() { }
    /** @see {m} */
    q() { }
}

Expected: goto-def/find-all-refs find the two references to m in jsdoc.

Actual: They don't.

Note that interfaces have the same problem:

interface C {
    m() 
    /** {@link m} */
    p()
    /** @see {n} */
    q()
    n: 1
}

Nested functions work fine:

function nestor() {
    function r2() { }
    /** {@link r2} */
    function ref() { }
    /** @see {r2} */
    function d3() { }
}
@sandersn sandersn self-assigned this Apr 8, 2021
@sandersn sandersn added the Bug A bug in TypeScript label Apr 8, 2021
@sandersn sandersn added this to the TypeScript 4.3.1 milestone Apr 8, 2021
@sandersn sandersn changed the title @link and @see should lookup sibling methods without a class prefix @link and @see should lookup sibling methods/properties without a class prefix Apr 8, 2021
@sandersn sandersn added Experience Enhancement Noncontroversial enhancements and removed Bug A bug in TypeScript labels Apr 8, 2021
@sandersn sandersn modified the milestones: TypeScript 4.3.1, Backlog Apr 8, 2021
@sandersn
Copy link
Member Author

sandersn commented Apr 8, 2021

Looking at this more closely, this is also a new feature -- In the examples above, there's no place to write a reference m that refers to the method m. Even C.m doesn't work -- it has to be C.prototype.m.

I put the test I wrote in the branch link-tag-method-name-resolution.

sandersn added a commit that referenced this issue May 21, 2021
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 typescript-bot added Fix Available A PR has been opened for this issue labels May 21, 2021
sandersn added a commit that referenced this issue May 26, 2021
* Add unqualified JSDoc member references

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

* Remove type/object literal container check

Since they don't work anyway
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
Experience Enhancement Noncontroversial enhancements Fix Available A PR has been opened for this issue
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants