Skip to content

Editor support for @see and {@link} in JSDoc comments tags #35524

Closed
@Elarcis

Description

@Elarcis

Search Terms

  • jsdoc @link
  • jsdoc @see
  • jsdoc @see @link

Suggestion

Reminder of what {@link} does

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-interactive mysterySymbol? 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Awaiting More FeedbackThis means we'd like to hear from more people who would be helped by this featureDomain: JSDocRelates to JSDoc parsing and type generationSuggestionAn idea for TypeScript

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions