Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

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

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in 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