How do I refer to another typescript type in comments/JSDoc?

Question

I'm familiar with Javadoc. In Javadoc, you can place a link that refers to the Javadoc placed on another type like so:

/**
 * some java thingy. see this other java thingy too {@link OtherThingy}
 */
public class Thingy { /*...*/ }

/**
 * some other java thingy. see the first java thingy too {@link Thingy}
 */
public class OtherThingy{ /*...*/ }

Can I do the same in typescript's flavor of JSDoc? I know that I can use markdown in the comments and I can place web links but that's not exactly what I'm going for.

Also, any references to JSDoc/typescript documentation tools would be very helpful :)

Edit: Per the answers below, this is a feature of JSDoc but doesn't seem to be included in VSCode. Is there an valid syntax in VSCode?

Answer 1

You sure can, though your mileage may vary.

1: A use of @link in Selenium-Webdriver's TypeScript typing file

/**
 * Converts a level name or value to a {@link logging.Level} value.
 * If the name/value is not recognized, {@link logging.Level.ALL}
 * will be returned.
 * @param {(number|string)} nameOrValue The log level name, or value, to
 *     convert .
 * @return {!logging.Level} The converted level.
 */
function getLevel(nameOrValue: string | number): Level;

2: Docs about @link in JSDoc

The following example shows all of the ways to provide link text for the {@link} tag: Providing link text

/**
 * See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
 * Also, check out {@link http://www.google.com|Google} and
 * {@link https://github.com GitHub}.
 */
function myFunction() {}

By default, the example above produces output similar to the following: Output for {@link} tags

See <a href="MyClass.html">MyClass</a> and <a 
href="MyClass.html#foo">MyClass's foo
property</a>. Also, check out <a 
href="http://www.google.com">Google</a> and
<a href="https://github.com">GitHub</a>.

Answer 2

With VSCode 1.52 (Nov. 2020), you might also consider another tag:

Initial support for JSDoc @see tags

JSDoc @see tags let you reference other functions and classes in your JSDoc comments.

The example below shows crash function referencing the WrappedError class from another 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 will now include basic @see references while performing renames.

You can also run go to definition on the @see tag's content and @see tags will also show up in the list of references.

We plan to continue improving support for @see tags in future releases.

As Mark notes in the comments:

• PR 119358 adds support for JSDoc link tags in VSCode 1.55 (March 2021)
• VSCode 1.57 (May 2021) adds @link support

JSDoc @link support

We now support JSDoc @link tags in JavaScript and TypeScript comments.

These let you create clickable links to a symbol in your documentation:

JSDoc @link tags are written as: {@link symbolName}.

You can also optionally specify text to be render in place of the symbol name: {@link class.property Alt text}.

@link is supported in hovers, suggestions, and signature help.
We have also updated vscode.d.ts to use @link.

---

Note: cachius adds in the comments:

import { MyClassName } from "path/to/MyClassName";

If MyClassName is not already imported, adding @see MyClassName in the JSDoc would only show any on hover and doesn't allow ctrl + clickthrough to declaration/usages.

Importing it allows that, even if the only mention is in the JSDoc.
This is useful when a module/class refers to some other logically, but without using it directly.

Unused imports might trigger eslint warnings though, which I'd silence in this case with:

// eslint-disable-next-line @typescript-eslint/no-unused-vars 

Answer 3

VS Code treats {@link} as a comment, so it doesn't get any special parsing (it's just displayed exactly as you typed it). There's currently an open issue to fix this, however.