Preface

I was struggling to find a feature to support exactly what I wanted, and I didn't see any open issues that were quite hitting the nail on the head either. Happy to take this discussion to another thread if it does happen to be a duplicate.

Problem Statement

Essentially, we have no way to share common documentation to reduce duplication. Some duplication is acceptable, but at scale, docs often fall out of sync and become inaccurate.

Why Today's Solutions Are Insufficient

Ultimately, we can either accept the limitations and try to compensate with HTML code-gen, or just suck it up and duplicate the docs. Maybe it's time we have another look?

Examples

/** Common greeting word. */
type Greeting = (typeof GREETINGS)[number];
  // ^ Common greeting word.

const GREETINGS = ['hi', 'hello', 'howdy'] as const;

/** @type {Greeting} */
const HI: typeof GREETINGS[0] = GREETINGS[0] satisfies Greeting;
   // ^ @type — {Greeting}

/** @type {Greeting} */
const HELLO: typeof GREETINGS[1] = GREETINGS[1] satisfies Greeting;
   // ^ @type — {Greeting}

/** @type {Greeting} - This greeting is common in southern US regions */
const HOWDY: typeof GREETINGS[2] = GREETINGS[2] satisfies Greeting;
   // ^ @type — {Greeting} - This greeting is common in southern US regions

// Above illustrates the unwanted obfuscation introduced by `@type {Greeting}`.

Visuals

Hovering the VALUES	Hovering the TYPE
The same problem as seen in pure JS:

Live Demo

See this TypeScript Playground example.

Proposal

It would be fantastic to have a simple way to define a non-type, doc-specific value that can be shared in multiple JSDoc comments. Ideally, this would always be available at the surface level.

• @docdef to define the reusable chunk.
• @doc to reference said chunk in multiple JSDoc comments.

Examples

/** @docdef {GreetingDoc} Common greeting word. */


/** @doc {GreetingDoc} */
type Greeting = (typeof GREETINGS)[number];
   // ^ Common greeting word.

const GREETINGS = ['hi', 'hello', 'howdy'] as const;

/** @doc {GreetingDoc} */
const HI: typeof GREETINGS[0] = GREETINGS[0];
   // ^ Common greeting word.

/** @doc {GreetingDoc} */
const HELLO: typeof GREETINGS[1] = GREETINGS[1];
   // ^ Common greeting word.

/** @doc {GreetingDoc} This greeting is common in southern US regions */
const HOWDY: typeof GREETINGS[2] = GREETINGS[2];
   // ^ Common greeting word. This greeting is common in southern US regions

// Above illustrates the desired result, defining and referencing a reusable doc in multiple comments.

Visuals

Hovering the VALUES	Hovering the TYPE

Use Cases

A feature like this could improve several real-world scenarios.

• Similar constants – identical docs across related values (as shown in the examples)
• Related utilities – multiple helpers tackling the same problem space from different angles.
• Families of functions – structural variations of the same function (factories, curried forms, higher-order wrappers).
• Alternative APIs – e.g. pull, pullAll, pullAllBy, pullAllWith, pullAt
• Cross-layer consistency – a field like name may exist in both business-layer and data-access models (split across tables), but its meaning and docs don’t change
• Cross-type consistency – apply the same docs across related but distinct constructs (e.g. a class EditContext, a function edit, and a constant EDIT_KEY may all share the same disclaimer).

Closing Remarks

I don't know how much effort this might be to pull off, but I would be willing to do a little research to find out, and potentially contribute this feature myself. I also don't know if this will trickle down to editors and IDEs like VSCode, IntelliJ, etc, or if those would require independently developed features to support this. Any context or references would be appreciated.

If nothing else, I hope this kicks off a conversation to demonstrate the want and need for this (or a similar) feature.