-
Notifications
You must be signed in to change notification settings - Fork 12.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Provide way to link to other files from JSDoc comments #47718
Comments
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 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 |
FWIW there's not necessarily one file. In some cases we collate the documentation from multiple declarations. |
From what I understand, you guys are saying that this is blocking microsoft/vscode#86564. Are there any updates on this? Would love to be able to link files, be it JS, or any file really.
|
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:
/**
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
*/
// -- 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.) |
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. If we were only able to use line numbers, then they'd become a problem to update over time. |
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 |
+1 Please add native support. |
Loving +1 that a user-friendly way of simply using |
+1 for @nickyonge proposal. |
+1 to Don't know much about the On an unrelated note... I soLvEd iT gUyS π€ͺ: |
@js1m I was able to make |
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:https://./../../lib/Task/index.ts#ITask
*/
const updateReport = (id: string, selected: ITask[]) => {} And it actually works, you can navigate to that file. |
@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 |
@terenc3 Try
comment style. I don't think I have special extensions to handle this. I use Mac OS if that makes a difference. |
Tried this on Mac OS and it works, on Windows 11 it doesn't: |
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 microsoft/vscode#86564 still open (?): /**
* [link](./other.ts)
* works in rendered hover, but not in document
*/ Screen CaptureScreen.Recording.2024-06-19.at.05.13.54.movand (as has been mentioned, since 2020 - although not on windows?): /**
* file:https://./other.ts
* works in document, but not in rendered hover
*/ I tried (unsuccessfully) to combine them to work in both.
|
Another way to use /** Schema for {@link projectService.repo.server.connect} options */ |
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. |
You can already link to other files. You can do /** @see file:https:///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 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 /** @template {import('./barfile.js').barFn} T99 */
function foo() { } The only caveat is that the type must be exported. You can also use /**
* @typedef {import('./barfile.js').barFn} ref
* @see {ref}
*/
function foo() { } |
Suggestion
π Search Terms
β Suggestion
On VS Code, we have a long standing feature request to support relative file paths inside JSDoc comments: microsoft/vscode#86564
For example, if if I have a file
folder/foo.ts
:Then anywhere the documentation for
foo
is shown, we should renderlink
as a clickable link tofolder/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 toProposal
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
:This would likely be a new field on
SymbolDisplayPart
The text was updated successfully, but these errors were encountered: