Provide way to link to other files from JSDoc comments

[mjbvz]

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

[RyanCavanaugh]

FWIW there's not necessarily one file. In some cases we collate the documentation from multiple declarations.

[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}?

[michaeldrotar]

We have a component that's using webhooks so it needs a public url to work and we wrote up docs on how to setup ngrok to use it and then hit the question of where to store it - I couldn't get anything to work well so adding my thoughts here for the discussion:

• ultimately any solution probably should work with @see, @link, and [markdown-style](links) but it might be tricky to stay backward compatible

• personally I'd love if [link](./path) was relative to the current file location like it is today but there was something else like [link](/path) relative to the repo root since I'm likely to want to reference things there and things that aren't in the usual import paths

  /**
  Uses the [foo-service's bar endpoint](https://github.com/org/foo-service/blob/trunk/docs/bar.md) to do things.
  
  Also look at our relative [doc](./doc.md) and our top-level [README](/README.md)
  
  @see {@link /README.md#using-foo-service how to use the foo service}
  @see /docs/using-services.md#foo
  */

• lastly, the only way for my foo function in foo.ts to reference bar in bar.ts is to import bar from ./bar but our code tooling will correctly say that bar isn't used and remove that import on save - so I think @see and @link would further benefit with a syntax for this that can also reference exported members so that clicking scrolls to the right line that references it - I saw things like @see BarClass#barProperty already works for things that are imported, so maybe something like @see ./bar.ts#BarClass#barProperty for things that aren't imported - double hash tag is a little odd but it's the most semantic thing I can think of cause it literally is an anchor to a spot in a file and it stays similar to the other syntax for class members

// -- foo.ts ---------------------
/**
  This function does foo stuff.
  See [bar](./bar.ts#bar) for an example of how to use it.

  @see ./bar.ts#BarClass#barProperty
*/
function foo() {}

// -- bar.ts ---------------------
import foo from './foo'

function bar() {
  foo()
}

class BarClass {
  barProperty: string
}

(Also for consideration: it'd ultimately be important for vscode and similar editors to be able to update the file paths here when files are renamed and the function, class, and property names when they're renamed to avoid breaking links, I'm assuming TS helps to feed data for those features to work.)

[airtonix]

It shouldn't just support line numbers, it should also support references to symbols (and other jsdoc created symbols).

Typedoc provides something similar to this.

We have design system components that use keys of our design system tokens as an abstraction. We'd like to be annotating those props with a link to the actual design tokens so it can help developers interpret figma designs.

If we were only able to use line numbers, then they'd become a problem to update over time.

[Domiii]

It shouldn't just support line numbers, it should also support references to symbols (and other jsdoc created symbols).

Agreed. That would be fantastic. Line numbers would, over time, always end up being incorrect, and cannot be verified by some sort of "link checker" either

[GlenPierce-Workday]

Rather than linking to a line number, could such a link... link to another specific symbol? @link theImportantDocumentation-> @target theImportantDocumentation ?

[joshuambg]

+1 Please add native support.

[nickyonge]

Loving +1 that a user-friendly way of simply using @link to refer to a relative file would be great. Personally would love inline for the format @see {@link ./myFile.js}

[lflorent]

+1 for @nickyonge proposal.

[Domiii]

I think, these are the three main wishes expressed in this thread:

1. relative links (ref)
2. direct links to dependencies (ref)
3. support for line + column numbers (ref)

[js1m]

+1 to {@link 'relative/path/file.ext:row?:col?'

Don't know much about the JSDoc ecosystem, but would be nice if it could resolve paths specified in jsconfig.js and tsconfig.ts. I guess this behaviour could be a flag in the IDE settings for better SOC and ultimately JSDoc configuration itself needing to support path mappings for this particular functionality.

On an unrelated note... I soLvEd iT gUyS 🤪: {@link file://./sibling.ext} -- I mean it does actually work for me on macOS@13.4 and vscode@1.82.2, but only for paths starting with ./ coudn't make ../ work lol. Absolute paths work for anything though if you wanna go there: file:///Users/babyshark/Desktop/doodoo.ext

[sagargurtu]

@js1m I was able to make ../ work by doing this {@link file://./../../sibling.ext}

[huksley]

thank you @sagargurtu, I think it is not a TypeScript thing but a VS Code thing, it allows you to reference file in a comment.

You can do this:

/**
 * Some bla bla from file://./../../lib/Task/index.ts#ITask
 */
const updateReport = (id: string, selected: ITask[]) => {}

And it actually works, you can navigate to that file.

[terenc3]

@huksley Are you sure that you don't have any extentions which provides this? Because for me it is not working. Neiter locally nor wsl. VS Code is always showing an error message "Unable to open.." and that it cannot create the file

[huksley]

@terenc3 Try

/**
 *
 */

comment style. I don't think I have special extensions to handle this. I use Mac OS if that makes a difference.

[madhugod]

/**
 * file://./../package.json
 */

Tried this on Mac OS and it works, on Windows 11 it doesn't: Unable to open 'package.json' 😞

[sebastian-fredriksson-bernholtz]

It would be great if a solution to this would support clickable links in both the document editor and the rendered hover.

I'm on Mac OS v14.3.1 VSCode 1.90.1 and found - with all extensions disabled, editor.links not explicitly set, and despite https://github.com/microsoft/vscode/issues/86564 still open (?):

/**
 * [link](./other.ts) 
 * works in rendered hover, but not in document
 */

Screen Capture

https://github.com/microsoft/TypeScript/assets/14281373/812ad386-4263-44d8-aab0-dac107860633

and (as has been mentioned, since 2020 - although not on windows?):

/**
 * file://./other.ts
 * works in document, but not in rendered hover
 */

I tried (unsuccessfully) to combine them to work in both.

```ts/** * // explicit relative paths * [markdown explicit](./other.ts) - rendered:works, document:not working * [markdown with explicit file](file://./other.ts) - rendered:wrong location, document:works * {@link file://./other.ts|link explicit} - rendered:not working, document:wrong location * {@link file://./other.ts} - rendered:not working, document:works * {@link [link markdown explicit](file://./other.ts)} - rendered:wrong location, document:works * file://./other.ts - rendered:not working, document:works * * // implicit relative paths * [markdown implicit](other.ts) - rendered:works, document:not working * [markdown with implicit file](file://other.ts) - rendered:wrong location, document:wrong location * {@link file://other.ts|link implicit} - rendered:not working, document:wrong location * {@link file://other.ts} - rendered:not working, document:wrong location * {@link [link markdown implicit](file://other.ts)} - rendered:wrong location, document:wrong location * file://other.ts - rendered:not working, document:wrong location */ ```  

[ghost]

Another way to use @link is to point it to a variable. Here I wanted to link to my Server class connect method but the current file did not import Server directly. So, I did this:

/** Schema for {@link projectService.repo.server.connect} options */

[legowerewolf]

The way we've been doing it at work is with type-only imports. An excerpt from our standards document, from the part on how we mark deprecations:

// file: newFunction.ts
export function newFunction() {}

//file: deprecatedFunction.ts
import type { newFunction } from "./newFunction"

/** @deprecated use {@link newFunction} */
function deprecatedFunction() {}

This results in clickable links, without impacting emitted code.

[clshortfuse]

You can already link to other files. You can do

/** @see file:///C:/jsproject/jsfile.js */
function foo() { }

And VSCode will find it. The problem is more that we don't have a way to specify relative paths with file:// so everything needs to be absolute.

You can also link to types declared in other files (if Typescript picks it up):

/** @see {FooObject} */
function foo() { }

You can even link to functions:

function foo() { }

/** @see {foo} */
function bar() { }

You cannot do this across files since import will not work. but @template does work, so you can hack the link into it with a useless template.

/** @template {import('./barfile.js').barFn} T99 */
function foo() { }

The only caveat is that the type must be exported.

You can also use @typedef instead, though it's leaky:

/**
 * @typedef {import('./barfile.js').barFn} ref
 * @see {ref}
 */
function foo() { }

[romulof]

This works in VSCode:

/**
 * {@link file://./foo.ts}
 */

Special note for when you try to go a level above, you still need to start with ./:

/**
 * {@link file://./../bar.ts}
 */

[seahindeniz]

Thanks @romulof, for the info about parent directory traversal. I additionally would like to add that the hyperlink rendering doesn't render as expected, but the functionality works when used with a relative path

/**
 * @see {@link file://./../../../@types/foo.d.ts}
 * @see {@link http://github.com}
 * @see {@link file://./../../../@types/foo.d.ts | Foo}
 * @see {@link http://github.com | GitHub}
 */