jsdoc / jsdoc/jsdoc

Is There A Way To Get JSDoc To Show The Return Value Of a @typedef Instead Of The @typedef Name Itself?

Open
#2,033 0 comments 0 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

I posted a question over at StackOverflow since it is a VS Code question specifically, but I'm asking here in the event that someone else might have a solution I could try since VS Code supports JSDoc comments.

I have a simple function with JSDoc comments.

/**
 * An object containing a person's details.
 * @typedef {Object} Person
 * @property {string} name - The person's name.
 * @property {number} age - The person's age.
 */

/**
 * Returns a person's name and age from a string.
 * @param {string} personDetails - The string containing the person's info.
 * @return {Person} An object containing `name` and `age` properties.
 */
const getPersonDetails = (personDetails) => {
  const [name, age] = personDetails.split(',');

  return {
    name: name,
    age: age,
  };
};

When I hover over the definition in VS Code I am shown the typedef name instead of the expected object with properties.

Hover On Definition - TypeDef Name Shown

const person = getPersonDetails('Bob,23');
console.log(person); // Hover: -> const person: Person

This approach does let me at least get a description for each property.

Hover On Definition - Descriptions Shown For Properties

console.log(person.name); // Hover: -> (property) name: string •The person's name.
console.log(person.age); //  Hover: -> (property) age: number •The person's age.

If I change the return from @return {Person} to {{name: string, age: number}} then I am shown the expected return value on hover, but now I do not get the descriptions for each property when referring to them, simply their type.

Hover On Definitions - Return Object Shows Properties But No Descriptions

console.log(person);
/* Hover:
const person: {
    name: string;
    age: number;
}
*/
console.log(person.name); // Hover: -> (property) name: string
console.log(person.age); //  Hover: -> (property) age: number

What I am looking to achieve is to get VS Code to show me both the actual object with properties that would be returned instead of the typedef name as well as descriptions for each property when hovering over them.

Is there a way to do this?

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

The issue names no repository files, tests, or entry points. Start by reproducing the shown JSDoc example and determining whether the hover behavior belongs to JSDoc or VS Code. Done would mean identifying a supported solution or a concrete, repository-scoped documentation change.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.