Description
Search Terms
jsdoc @link
jsdoc @see
jsdoc @see @link
Suggestion
Whenever a {@link}
tag is encountered in JSDoc, it’d be nice to have it formatted as an actual anchor. It works with URL and symbols relative to the documented one: a function, a property of the current class, or a function in another class?
The @see
tag can also reference a symbol without any {@link}
, provided there is only a path to a symbol and no free-form text next to it. https://jsdoc.app/tags-see.html
Use Cases
I often speak of other functions/classes in my doc comments, and as {@link}
is described on JSDoc’s website, it’d be nice to have it parsed by the langage server and have it shown as a clickable link in any compatible doc widget.
Examples
import { Blah } from "./blah";
/**
* This won’t work due to scope: {@link baz}
* This will: {@link Foo#baz}
*
*
* The @see annotation can reference symbols as well, as stated on
* {@link https://jsdoc.app/tags-see.html JSDoc’s website}
* @see Document
*/
class Foo<T> {
/** I want a link to {@link bar}. */
private baz: T;
/** But I can also reference {@link Foo | the parent class}. */
public bar(): T {
return this.baz;
}
/** @deprecated please use {@link Blah#grog} instead. */
public grog(): void {}
/** What to do with this link? {@link mysterySymbol} */
public grug(): void {}
}
Non-imported symbols
A question that subsists is “what to do when {@link} refers to a symbol that exists in the project but isn’t imported in the current file?”
- Do nothing?
{@link mysterySymbol}
is converted into a basic non-interactivemysterySymbol
? Con is that to get a working link, you’d have to import symbols that are only used for doc. - Allow an
import("the-module").mysterySymbol
syntax like what was done for types declarations? - Do a “best guess” and instead of directly going to a
file:line:column
, find all references of the given symbol in the project and somehow make the editor open a “peek” widget? - What if the symbol is located in a dependency, i.e.
node_module
?
Checklist
My suggestion meets these guidelines:
- This wouldn't be a breaking change in existing TypeScript/JavaScript code
- This wouldn't change the runtime behavior of existing JavaScript code
- This could be implemented without emitting different JS based on the types of the expressions
- This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
- This feature would agree with the rest of TypeScript's Design Goals.