jsdoc / jsdoc/jsdoc

Allow `@link` to reference objects in other files

Open
#1,993 6 comments 69 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
15.5k
Forks
1.5k
Avg merge
10d 23h
Merged PRs (30d)
1

Description

In @type (and other type defining tags) it's possible to reference external JS objects by using import("./relative/path").objectName.

This should also be possible in @link both to avoid importing unexecuted code, and to avoid errors in common tools & frameworks regarding the unused imports.

Input code
/**
 * @see {@link import("./file.js").objectName} this thing may be of interest for reasons
 */
/* ... */
Expected behavior

The @link inline tag should provide a reference to the exported objectName in ./file.js

Current behavior

The @link tag does not provide any reference, and (at least when using VSCode to render) shows up as the plaintext import("./file.js").objectName instead of a clickable link

Your environment
Software Version
JSDoc (supplied with VSCode 1.67)
Node.js 18.2.0
npm 8.9.0
Operating system Linux (Pop OS 21.10)
Why this functionality matters

I use TypeScript for pretty much everything I write at this point. I want my JS output to be the absolute minimum it needs to be, because my DTS will do all the in-editor documentation; I set removeComments = true for JS and = false for DTS.
However, because I have to import the objects I want to reference in @link, and because TypeScript is "helpful" and treeshakes unused imports, they've been removed by the time my DTS files are generated with JSDoc preserved. However, this now means that my @link tags no longer work.
There is a TypeScript issue to add support for @link targets being treated as "used" values, however it could be useful in many cases for JSDoc to support the import(file).member syntax in @link as well as TypeScript fixing it's own behavior.


If this is supposed to be possible, and is just VSCode not rendering JSDoc correctly, let me know and I'll bring up this issue over there instead

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the supplied JSDoc example and tracing how the @link inline tag resolves targets, using the documented import("./file.js").objectName syntax as the reference case. Done means the external export is resolved as a clickable link rather than rendered as plaintext, without requiring an import in the source file.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.