Provide way to link to other files from JSDoc comments

Suggestion

🔍 Search Terms

• quickInfo
• markdown
• link
• relative path
• jsdoc

⭐ Suggestion

On VS Code, we have a long standing feature request to support relative file paths inside JSDoc comments: https://github.com/microsoft/vscode/issues/86564

For example, if if I have a file folder/foo.ts:

/**
 * [link](./other.js)
 */
export declare function foo(x: string, y: {}): void

Then anywhere the documentation for foo is shown, we should render link as a clickable link to folder/other.ts.

On the VS Code side today, we can support rendering link but do not know what relative paths inside the documentation should be relative to

Proposal

To fix this, I propose that requests that return documentation also include a path that tells us which file the documentation comes from

Here’s an example using quickInfo:

[Trace  - 17:11:37.514] <semantic> Response received: quickinfo (292). Request took 2 ms. Success: true 
Result: {
    "kind": "function",
    "kindModifiers": "export,declare",
    "start": { "line": 4, "offset": 25    },
    "end": { "line": 4, "offset": 28 },
    "displayString": "function foo(x: string, y: {}): void",
    "documentation": [
        {
            "text": "[link](./files.js)",
            "kind": "text",

             // new field
             "file": "/absolute/path/to/folder/foo.ts"
        }
    ],
    "tags": []
}

This would likely be a new field on SymbolDisplayPart

[mjbvz]

Not a huge fan of my original proposal actually

Instead of markdown, I think we should investigate adding proper file link support to JSDoc. As far as I can tell this isn’t supported in the jsdoc spec

Here’s what this could look like using our existing @link support:

/**
 * {@link import('./main.ts') link}
 */
declare function foo(x: string, y: {}): void

Or we could come up with some new way to express file links:

/**
 * {@linkfile ./main.ts link}
 */
export declare function foo(x: string, y: {}): void

Having proper semantic file link support would be nice as we could include these references when you run find all reference to file and update them when you move a file

[Domiii]

From what I understand, you guys are saying that this is blocking https://github.com/microsoft/vscode/issues/86564.

Are there any updates on this? Would love to be able to link files, be it JS, or any file really.

• I would also like to ask if its possible to add line/column numbers, as though you just throw it to the code CLI?
  • E.g. {@linkfile ../../x/y/z.js:42}
• And another one: could we have support to have file links relative to a module name, iff the url does not start with (i) ., (ii) root or (iii) protocol?
  • E.g. {@linkfile my-module/x/y/z.js:42} instead of {@linkfile ../../../node_modules/my-module/x/y/z.js:42}?