Absolutely, the @link feature is fully functional
You have the capability to utilize {@link OtherThingy} in your documentation, and it has been operational within VS Code since the year 2021. Simply incorporate it for inline referencing.
Detailed information and additional choices
In addition to using the aforementioned approach, when dealing with VSCode version 1.52 (released in November 2020), you may also contemplate employing an alternative tag:
The utilization of JSDoc @see tags facilitates references to various functions and classes within your JSDoc comments.
An illustration below illustrates a scenario where the crash function refers to the WrappedError class from a distinct file:
// @filename: somewhere.ts
export class WrappedError extends Error { ... }
// @filename: ace.ts
import { WrappedError } from './somewhere'
/**
* @see {WrappedError}
*/
function crash(kind) {
throw new WrappedError(kind);
}
VS Code now encompasses rudimentary @see references during rename operations.
Furthermore, by executing go-to-definition on the @see tag's content, and incorporating @see tags within the list of references, enhanced support for these features is anticipated in forthcoming updates.
Mark points out in the discussions that:
JSDoc @link inclusion
We are pleased to announce the inclusion of JSDoc @link tags functionality within JavaScript and TypeScript comments.
These tags allow for the creation of interactive links to symbols within your documentation:
https://i.sstatic.net/RpXVp.gif
JSDoc @link tags adhere to the format: {@link symbolName}.
If desired, you can specify alternate text to display instead of the symbol name: {@link class.property Alt text}.
@link integration extends to hovers, suggestions, and signature assistance.
We have also updated vscode.d.ts to encompass @link elements.
Please note: cachius expresses insights in the remarks:
import { MyClassName } from "path/to/MyClassName";
If MyClassName remains unimported, including @see MyClassName within the JSDoc would merely exhibit any upon hover, without enabling ctrl + clickthrough functionality to declarations/usages.
By importing the type, this limitation is overcome, even if the sole occurrence exists within the JSDoc commentary.
This practice proves beneficial when modules/classes reference each other conceptually, albeit without direct usage.
Nevertheless, unused imports could trigger eslint alerts, which can be suppressed utilizing:
// eslint-disable-next-line @typescript-eslint/no-unused-vars
Daniel Steigerwald supplements the discussion with insights in the comments
It is imperative that the imported type is actively utilized.
Failure to do so renders the JSDoc processing ineffective.
Moreover:
An additional critical issue arises when destructuring occurs, as any portion of JSDoc featuring @ is disregarded, consequently rendering it ineffectual.
To mitigate such occurrences, all instances of @example need substitution with Markdown annotations, like ### Example ts ...
Eric Haynes adds further perspective in the responses:
Consider opting for the following approach:
import type { MyClassName } from 'path/to/MyClassName';
Type imports undergo removal during compilation, unlike traditional imports within the compiled JavaScript.
(or
import { type MyClassName, OtherThing }
if another import already exists along that path)
Utilizing import { type Foo } appears to present a viable solution.
Nonetheless, despite the absence of the
typescript Foo is declared but its value is never read
warning, errors relating to no-unused-vars eslint pertaining to the import might persist.
Is there a workaround for this issue or does it signify an eslint anomaly?
Although TypeScript acknowledges the import's purpose for type delineation, thereby eliminating it in transpiled JavaScript, ESLint's default settings may not recognize type-only imports as "utilized". Consequently, such entities are tagged as unused variables by ESLint.
One potential resolution involves customizing the ESLint configuration to overlook unused vars solely imported for types. This can be achieved by adjusting the no-unused-vars rule within your .eslintrc setup, particularly leveraging the ignoreRestSiblings and argsIgnorePattern options to exclude type imports:
{
"rules": {
"no-unused-vars": ["error", { "ignoreRestSiblings": true, "argsIgnorePattern": "^_" }],
"@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
}
}
This method mandates tweaking to pinpoint type imports while steering clear of inadvertently silencing genuinely unused variables.
An alternative route entails integrating the eslint-plugin-import plugin, offering refined control over linting matters associated with imports. This plugin introduces a rule named import/no-unused-modules, which allows configurations conducive to type-only imports. Implement the necessary adjustments within your .eslintrc after installing the plugin:
{
"plugins": ["import"],
"rules": {
"import/no-unused-modules": [1, { "ignoreExports": ["path/to/your/typescript/files/**/*.ts"] }]
}
}
You should define paths and matching patterns relevant to your project structure: although more upfront effort is required, accuracy in linting behavior management improves.
If the concern arises sporadically and global ESLint alterations seem unwarranted, consider deactivating the ESLint rule exclusively for specific imports:
// eslint-disable-next-line no-unused-vars
import { type Foo } from './foo';
In projects reliant on the @typescript-eslint plugin (highly recommended for TypeScript endeavors), leverage its augmented version of the no-unused-vars rule. Verify that your ESLint setup accesses this revised rule, rather than the conventional variant:
{
"extends": [
"plugin:@typescript-eslint/recommended"
],
"rules": {
"no-unused-vars": "off", // Disable base ESLint edition
"@typescript-eslint/no-unused-vars": ["error"] // Employ TypeScript ESLint interpretation
}
}
The adapted rule demonstrates elevated proficiency in recognizing TypeScript-specific traits of type-only imports, thus averting redundant flags indicating their underuse.