Jsdoc https @link text not parsed properly

[NorthBlue333]

TS Template added by @mjbvz

TypeScript Version: 4.6.0-dev.20211108

Search Terms

• jsdoc
• quick info

---

Does this issue occur when all extensions are disabled?: Yes

After searching the issues, I have found relevant ones :

• External jsdoc @link text not displaying properly with May 2021 update vscode#126180
• JSDoc @link tag does not support urls anymore vscode#126626 (closed as duplicates of the first one)

They are closed since v1.58.0 with this commit microsoft/vscode@7339e94. I don't know if they are related or not.

---

Using VSCode v1.62 shipped with TypeScript v4.4.3, the url gets splitted after https?.

Using TypeScript v4.2.4 only URLs work, not symbols.

Using TypeScript v4.3.5, everything works fine.

I do not understand why the JSDoc implementation on VSCode is dependent of TypeScript version even in pure JS files. I apologize if TypeScript version older than v4.3 are not supported, and I think they are not by reading the issues about implementing @link.

There is still an issue with the latest version.

I currently do not have the time to investigate more, sorry for that. Thanks for reading me!

Here is the sample of code I used :

class MyClass {
  foo;
}

/**
 * See {@link MyClass} and {@link MyClass.foo foo}.
 * Also, check out {@link http://www.google.com} and
 * {@link https://github.com GitHub}.
 * 
 * 
 * 
 */
function myFunction() {}

VSCode About section :

Version: 1.62.0
Commit: b3318bc0524af3d74034b8bb8a64df0ccf35549a
Date: 2021-11-03T15:18:44.904Z
Electron: 13.5.1
Chrome: 91.0.4472.164
Node.js: 14.16.0
V8: 9.1.269.39-electron.0
OS: Linux x64 5.4.0-89-generic

[mjbvz]

@link for symbols was added in TS 4.3 so they will not work on older versions

Moving the {@link http://www.google.com} case upstream for TS to take a look since it gets parsed incorrectly

[mjbvz]

For:

/**
 {@link http://www.google.com}
  */
function myFunction() {}

The returned quickInfo is:

"documentation": [
        {
            "text": "",
            "kind": "text"
        },
        {
            "text": "{@link ",
            "kind": "link"
        },
        {
            "text": "http ://www.google.com",
            "kind": "linkText"
        },
        {
            "text": "}",
            "kind": "link"
        }
    ],

[fatcerberus]

I do not understand why the JSDoc implementation on VSCode is dependent of TypeScript version even in pure JS files.

VSCode uses the TypeScript language service for IntelliSense in both JavaScript and TypeScript. This includes JSDoc parsing, which TS implements because it can optionally use it for type checking with checkJs.

[SchoofsKelvin]

There's another issue regarding the display text for @link tags. According to the TSDoc specification and its dependant API Extractor, if we want the display text to be different from the reference, we need to use {@link DECLARATION_REFERENCE | DISPLAY_TEXT}. But doing it this way results in the following tooltip in VS Code:

Notice how the vertical bar (|) is included, even though it is not meant to be included.

While removing the vertical bar does make it display the correct text in the tooltip, this goes against the above documentation, their example code and even the official tsdoc library, as the latter will output a tsdoc-reference-missing-dot warning, since it thinks it's still parsing a declaration reference due to not encountering a vertical bar.

It's worth mentioning that JSDoc does allow omitting the vertical bar, but it also supports having the vertical bar. Their examples showcase that if a vertical bar is used, it isn't displayed, similar to how TSDoc handles the vertical bar.

Tested using TypeScript versions 4.4.4 and 4.5.4

[sandersn]

@SchoofsKelvin can you open a separate bug for that? It's worth fixing, but from my perspective it's a separate feature than correctly keeping http and :// together.