Add support for JSDoc links in editors

[mjbvz]

Feature request

Support rendering the JSDoc {@link ...} and {@linkcode } syntax. These links should be rendered in hovers and suggestion details

Here's the VS Code side of the implementation where we convert SymbolDisplayPart to a markdown string for use in the editor

We use these links heavily in our typings for extension authors and have found them to be very useful

[ahejlsberg]

I'll be happy to get this done, but looking at the old code there are so many transformations and indirections that it isn't clear to me what should be implemented. Can you describe the desired transformations in more detail?

I should add, {@link ...} to symbols and URLs seem to work fine, so examples of what isn't working would be great.

[mjbvz]

I'm mainly interested in the editor/tooling part of this so I am unsure about transformations. Here's a some more details on what we're looking for on the editor side though:

For example code such as:

class Animal { }

/**
 * An {@link Animal}, specifically a cat
 */
class Cat extends Animal { } 

I should be able to hover over Cat and see a clickable link to Animal:

Clicking on this link should take me to Animal

---

Previously in VS Code, this was implemented by returning SymbolDisplayPart link entries in the quick info / documentation. We could then convert these into markdown links to the resolved location in code. Here's the relevant code in the VS Code TS extension

Now that TS owns the language server, I think we can simplify this so that TS generates the markdown string directly for hovers and other documentation

[ahejlsberg]

@mjbvz Got it. It's easy enough to make http links work by formatting into [...](https://xxx) blocks, but I'm having a harder time with symbolic links to file locations. Formatting into [...](vscode://file/xxx) doesn't seem to work. Is there some other magic that's needed?

[jakebailey]

The old extension appears to use a command to do this (https://github.com/microsoft/vscode/blob/b5903ae54c35d78b8ed2fd82a7dcf31764191de7/extensions/typescript-language-features/src/languageFeatures/util/textRendering.ts#L163C34-L163C54), e.g. a link to command:....

But doing this means we would have to declare that our markdown handling is trusted when constructing the language server, pretty sure, and the command that the original extension uses wouldn't exist when the tsgo extension is loaded.

I feel like there has to be a way to do this without involving a command. I don't think every language server is encoding client-specific stuff like this? That would be weird...

I don't think vscode:// is the right format; can you try just using the URLs for the file we'd normally give back over LSP, e.g. file://c:/foo/bar and so on?

[ahejlsberg]

I'm finding is that file://c:/foo/bar/t.ts works, but only if you turn security.restrictUNCAccess off. And then, it still doesn't support going to a specific line and column.

Meanwhile vscode://file/c:/foo/bar/t.ts:4:1 works in a markdown file, but seems to be ignored in hover markdown.

[jakebailey]

These are the formats that are supposed to work to link to specific positions: https://github.com/microsoft/vscode/blob/b3ec8181fc49f5462b5128f38e0723ae85e295c2/src/vs/platform/opener/common/opener.ts#L151-L160

I am not sure about the UNC thing, but I bet there's a way around that for Windows-style paths. Maybe file:///c/foo/bar/x.ts?