Handle JSDoc {@link ... } inline tags

[mjbvz]

From: microsoft/vscode#28624

TypeScript Version: 2.3.5

Code

/**
 * @see {@link https://api.jquery.com/bind/#bind-eventType-eventData-handler}
 */
function foo() {
    
}

Hover over foo

Bug
The following docs are returned:

Result: {
    "kind": "function",
    "kindModifiers": "",
    "start": {
        "line": 4,
        "offset": 10
    },
    "end": {
        "line": 4,
        "offset": 13
    },
    "displayString": "function foo(): void",
    "documentation": "",
    "tags": [
        {
            "name": "see",
            "text": "{"
        },
        {
            "name": "link",
            "text": "https://api.jquery.com/bind/#bind-eventType-eventData-handler}"
        }
    ]
}

[kevinSuttle]

Just an FYI to VSCode users: you can use Markdown, which will render properly in the quick info popover UI. You won't get the syntax highlighting, though.

/**
 * [Link](https://example.com)
 */

You can also just use a plain URL now

/**
 * https://example.com
 */

[thw0rted]

Does this also address {@link OtherClass.method} ? (Is that the right way to link to a member of another class that JSDoc knows about?)

[Duckers]

It would be awesome if links to language entities also worked with refactoring, so you can safely refactor entity names without invalidating documentation that talks about those members.

[Rhysjc]

This doesn't seem to be fixed in the latest release. Any update?

[sandersn]

@Rhysjc we're still accepting PRs for this one.

This is primarily a parsing problem, and not an easy one, since {@link ... } doesn't look like any other JSDoc tags we support. It would be good if you're familiar with our parser, or are familiar with parsing in general and want to learn the quirks of ours.

Any solution will also have to decide whether @link is a child of whatever tag it appears in. The easy answer is 'no' since only a few tags can have children. But that would mean you would need to check that VS code displays a sequence of tags that includes @link in a pleasing way.

[DanielRosenwasser]

Linking to the VS UserVoice as well: https://visualstudio.uservoice.com/forums/121579-visual-studio-ide/suggestions/12796299-support-jsdoc-link-in-typescript

[fredrikhr]

For what it is worth, I have written up my understanding of how the behaviour should be for rendering according to the cases specified on the Use JSDoc website. See my duplicate, now closed, issue: microsoft/vscode#57495 (comment)

[pvoisin]

What's going to happen with that issue? :)

[mjbvz]

VS Code 1.43 insiders will add support for {@link } with http/https uris.

@sandersn We are still blocked on {@link Symbol} as editors cannot reasonably resolve the referenced symbol using the current TSServer apis (one big issue is that Symbol needs to be resolved in the scope of the definition, not at usage). We need TS to tell us where symbol links should go to

Related #35524

[sandersn]

#35524 is a good start on a proposal. Let's track Typescript-based handling of @link there -- particularly binding.

[minestarks]

@mjbvz @sandersn just throwing it out there, if a "horrible regex to handle this" is on the table, could we at least put that handling in the language service (e.g. in the implementation of quickinfo, or wherever else we want to surface this) instead of VS Code? This way all editors get the benefit but we can still defer the trickier parsing questions to #35524.

[minestarks]

@mjbvz @sandersn what is this issue supposed to be tracking at the moment? is it a dupe of #35524 ?

[sandersn]

Yes, I think it is at this point.

[rainmanhhh]

after 2 years {@link ...} still not work?

[brokenthorn]

after 2 years {@link ...} still not work?

It's a complex issue. As you can see, it depends on TSServer functionality which is not ready. This is more complicated than it seems because of information that needs to come from context. But it seems to be coming soon.

[babak1199]

Didn't see any mention of {@link external:XMLHttpRequest}. I hope it's part of the design too.

[ghost]

The issue continues here with more detail: #35524

[qJake]

The bottom of this page should be updated with the new issue tracking link, if {@link Symbol} is still not yet supported.

People coming here from there (myself included), see this as closed and assume {@link} works across the board.

Is there a repo I can file a bug for that site to get it updated?

[minestarks]

@qJake https://github.com/microsoft/TypeScript-Website
cc @orta

[orta]

Cool, I've updated the number on staging - it'll either get deployed some time this week or on the normal Monday deploy cycle.

[Gaibhne]

This issue should not be closed, this still happens in the latest version.

[panlina]

Any update on this issue? This issue should not be closed.

[amcasey]

@Gaibhne @panlina Are you running typescript@next (aka nightly)? As far as I know, this is not yet available in the the version shipped with VS Code.

[Gaibhne]

I'm using the regular stable release. As this issue was tagged as merged in May 2020, it would be merged for almost a whole year. Surely, it wouldn't still be stuck in nightly after all this time ?

[amcasey]

@Gaibhne I can't speak to the tagging, but the PR was only merged two weeks ago: #43312

[MartinJohns]

This issue only related to {@link ...} tags containing http/https urls, and it works already. The other issue #35524 handles links to symbols and only got merged three weeks ago.

Just read the comments on this thread:

• Handle JSDoc {@link ... } inline tags #16498 (comment)
• Handle JSDoc {@link ... } inline tags #16498 (comment)

[misha-erm]

This issue only related to {@link ...} tags containing http/https urls, and it works already. The other issue #35524 handles links to symbols and only got merged three weeks ago.

Just read the comments on this thread:

• Handle JSDoc {@link ... } inline tags #16498 (comment)
• Handle JSDoc {@link ... } inline tags #16498 (comment)

@MartinJohns looks like it doesn't work for me still. Links in hover popups aren't clickable and doesn't look like URLs

/**
 * React hook to support both controlled/uncontrolled modes
 * @see {@link https://reactjs.org/docs/uncontrolled-components.html}
 */

It only start to work when I put link into brackets or some other characters like this @see {@link (https://reactjs.org/docs/uncontrolled-components.html)}

[sandersn]

@MikeYermolayev please open a new issue for this. I believe the space after https is fixed in recent typescript builds, though, so check that out first.

[Gaibhne]

Both the original issue, the issue of it only working with brackets and the issue with the erroneous space are all fixed in the current version, so I am unsubscribing to this issue - thank you for fixing this!

[bradennapier]

@mjbvz

There is currently a disconnect, i believe due to evolution of the @link definitions in the language service that creates a disconnect currently from tsdoc specification / typedoc

I am not completely sure which side the disconnect is on, (typescript language service/vscode/typedoc/tsdoc) but the @link provides a LOT of opportunity to help users learn how to use a package as they actually code rather than referencing external website all the time.

I am leaning towards this being a typedoc/tsdoc bug (which is why the item below was opened there), but figured it may be worth looking into on the vscode side to utilize the language services features around the Declaration References

Screenshots of the disconnect in the issue linked below

• @link is Disconnected from VSCode - Makes @link near-impossible to use effectively TypeStrong/typedoc#2141

[sandersn]

@bradennapier for the vscode side of the example you give in the bug you link, name resolution is happening using normal typescript rules. I don't expect to change that. The typedoc resolution looks like a bug to me -- whether it's a spec bug or an implementation bug I'm not sure.

[bradennapier]

@sandersn yes that is as I thought, just wanted to make sure to mention here in case something seemed odd! Definitely better to resolve via actual imported values than always trying to match symbols globally -- can imagine that would get out of hand quickly.

Thanks for the reply, I appreciate your time.