gajus/eslint-plugin-jsdoc

Rule suggestion: enforce proper `@see` + `@link` syntax for hyperlinks

Closed

#1,631 opened on Jan 20, 2026

View on GitHubContributor guide
 (1 comment) (4 reactions) (0 assignees)JavaScript (177 forks)github user discovery
enhancementhelp wanted

Repository metrics

Stars
 (1,227 stars)
PR merge metrics
 (Avg merge 2d 8h) (10 merged PRs in 30d)

Description

Motivation

As of filing, I know of two syntaxes for saying a user can @see a link:

  • At-Linked: @see {@link https://example.com|Example}
  • Markdown: @see [Example](https://example.com)

For consistency's sake, I think it would be nice to have a lint rule to prefer one and auto-fix the other to it.

Current behavior

No lint rule enforces either.

Desired behavior

I'm not sure. The Markdown variant is fewer characters, but the At-Linked one seems to be more of a "proper" link through JSDoc @link, so perhaps that?

Both show up well in at least TypeScript's native intellisense. The Markdown variant isn't perfectly supported by VS Code's native syntax highlighter, but that strikes me as a bug and not a motivator for choosing one over the other.

Alternatives considered

🤷

Contributor guide

Research direction
Examine existing JSDoc rules in the plugin (e.g., `require description`, `check access`) to understand the pattern for implementing a new rule. Prototype a rule that enforces a consistent `@see` + `@link` syntax, considering auto fix capabilities.
Tech stack
javascript
Domain
developer experience
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
ESLintJSDoc
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70