Repository navigation
Handle JSDoc {@link ... } inline tags #16498
Description
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}"
}
]
}
Activity
[-]Handle JSDoc `{@link ... }` inline blocks[/-][+]Handle JSDoc `{@link ... }` inline tags[/+]kevinSuttle commentedon Feb 20, 2018
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.
You can also just use a plain URL now
thw0rted commentedon Apr 26, 2018
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 commentedon May 17, 2018
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 commentedon Jun 7, 2018
This doesn't seem to be fixed in the latest release. Any update?
sandersn commentedon Jun 7, 2018
Rhys Camm (@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
@linkis 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@linkin a pleasing way.DanielRosenwasser commentedon Jun 21, 2018
Linking to the VS UserVoice as well: https://visualstudio.uservoice.com/forums/121579-visual-studio-ide/suggestions/12796299-support-jsdoc-link-in-typescript
24 remaining items
minestarks commentedon Aug 31, 2020
Jake Burgy (@qJake) https://github.com/microsoft/TypeScript-Website
cc Orta Therox (@orta)
orta commentedon Sep 1, 2020
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 commentedon Apr 1, 2021
This issue should not be closed, this still happens in the latest version.
panlina commentedon Apr 5, 2021
Any update on this issue? This issue should not be closed.
amcasey commentedon Apr 6, 2021
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 commentedon Apr 6, 2021
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 commentedon Apr 6, 2021
Gaibhne I can't speak to the tagging, but the PR was only merged two weeks ago: #43312
MartinJohns commentedon Apr 6, 2021
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:
{@link ... }inline tags #16498 (comment){@link ... }inline tags #16498 (comment)misha-erm commentedon Feb 16, 2022
Martin Johns (@MartinJohns) looks like it doesn't work for me still. Links in hover popups aren't clickable and doesn't look like URLs
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 commentedon Feb 16, 2022
@MikeYermolayev please open a new issue for this. I believe the space after
httpsis fixed in recent typescript builds, though, so check that out first.Gaibhne commentedon Mar 11, 2022
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 commentedon Jan 22, 2023
Matt Bierner (@mjbvz)
There is currently a disconnect, i believe due to evolution of the
@linkdefinitions in the language service that creates a disconnect currently fromtsdocspecification /typedocI am not completely sure which side the disconnect is on, (typescript language service/vscode/typedoc/tsdoc) but the Link (@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/tsdocbug (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 Referencessandersn commentedon Jan 23, 2023
Braden Napier (@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 commentedon Jan 25, 2023
Nathan Shively-Sanders (@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.