Skip to content

JSDoc comment for destructuring param: description text not displayed #24746

Open
Open
JSDoc comment for destructuring param: description text not displayed#24746
Labels
BugA bug in TypeScriptDomain: JSDocRelates to JSDoc parsing and type generationHelp WantedYou can do this
Milestone
Backlog

Description

@steph643
Steve Colbow (steph643)
opened on Jun 7, 2018

TypeScript Version:
2.9

Search Terms:
JSDoc destructuring param

Code

/**
 * @param {Object} arg
 * @param {number} arg.id - This param description won't show up
 */
function foo({ id }) {}

Expected behavior:
In VSCode 1.24.0, when typing foo(, IntelliSense should display the full param description, including its type and text.

Actual behavior:
The type is displayed ("number"), but not the text ("This param description won't show up"):
image

Related Issues:
#19645

Additional remark
When omitting the {Object} line, the param text shows up correctly:
image

Activity

  1. Mohamed Hegazy (mhegazy)
    added
    BugA bug in TypeScript
    Domain: JSDocRelates to JSDoc parsing and type generation
    Help WantedYou can do this
    on Jun 7, 2018
  2. Mohamed Hegazy (mhegazy)
    added this to the Community milestone on Jun 7, 2018

  3. mhegazy commented on Jun 7, 2018

    @mhegazy
    Mohamed Hegazy (mhegazy)
    on Jun 7, 2018
    Contributor

    PRs welcomed.

  4. rbiggs commented on Jul 6, 2018

    @rbiggs
    Robert Biggs (rbiggs)
    on Jul 6, 2018

    That's because TypeScript treats JSDoc types object and Object as any. You can designate a generic object using Object.<string, any>. So, redoing the above will give you the proper intellisense for id:

    /**
 * @param {Object.<string, any>} arg
 * @param {number} arg.id - This param description will show up
 */
function foo({ id }) {}

// Intellisense for id will work
foo({id: 1})

  5. tannerbaum commented on Sep 14, 2018

    @tannerbaum
    Tanner Hoisington (tannerbaum)
    on Sep 14, 2018

    Robert Biggs (@rbiggs) That does indeed work. However, VSCode only displays the description of the first parameter in the destructured object.

    screen shot 2018-09-14 at 12 06 04

    screen shot 2018-09-14 at 12 09 48

    I feel like we are so close here!

  6. rbiggs commented on Sep 14, 2018

    @rbiggs
    Robert Biggs (rbiggs)
    on Sep 14, 2018

    @THoisington, for that to work, you need to first define a custom object for the options, and then define its properties. Then you assign that custom type as your parameter:

    /**
 * Entries Object.
 * @typedef {Object.<string, any>} requiredArguments
 * @property {string} timeSince
 * @property {string} timeUntil
 */
/**
 * 
 * @param {requiredArguments} param
 */
async function getEntries({timeSince, timeUntil}) {}

    That'll give you IntelliSense for each property on the options parameter.

  7. tannerbaum commented on Sep 17, 2018

    @tannerbaum
    Tanner Hoisington (tannerbaum)
    on Sep 17, 2018

    This appears to have popped up in several issues, perhaps there could be some consolidation: #11597 and #11859, for example.

    Robert Biggs (@rbiggs) , I attempted your solution and found the vscode intellisense didn't display the subkeys or comments at all when using the @typedef and @property combination.

    At the risk of making a huge comment, I will document my findings here.

    Outcome 1: ❌ Top level details, ❌ subkey descriptions, ❌ current subkey highlighting.

    screen shot 2018-09-17 at 16 28 17

    screen shot 2018-09-17 at 16 29 27

    JSDOC that caused this:

    /**
 * @typedef {Object} requiredArguments
 * @property {string} timeSince Beginning date for the range...
 * @property {string} timeUntil End date for the range...
 */
/**
 * @param {requiredArguments}
 * @param {*} options - { filterUserId, filterCustomerId ... }
 * @see https://www.clockodo.com/en/api/entries/
 */
    /**
 * @param {Object} requiredArguments
 * @param {string} requiredArguments.timeSince - Beginning date for the range...
 * @param {string} requiredArguments.timeUntil - End date for the range...
 * @param {Object} options { filterUserId, filterCustomerId ... }
 * @see https://www.clockodo.com/en/api/entries/
 */
    /**
 * @typedef {Object.<string, any>} RequiredArguments
 * @property {string} RequiredArguments.timeSince - Beginning date for the range...
 * @property {string} RequiredArguments.timeUntil - End date for the range...
 */
/**
 * @param {RequiredArguments} params
 * @param {Object} options { filterUserId, filterCustomerId ... }
 */

    Outcome 2: ✅ Top level details, ✅ subkey descriptions, ❌ current subkey highlighting.

    screen shot 2018-09-17 at 16 33 29

    screen shot 2018-09-17 at 16 33 46

    JSDOC that caused this:

    /**
 * @typedef {Object.<string, any>} RequiredArguments
 * @param {string} timeSince - Beginning date for the range...
 * @param {string} timeUntil - End date for the range...
 */
/**
 * @param {RequiredArguments} params
 * @param {Object} options { filterUserId, filterCustomerId ... }
 */
    /**
 * @typedef {Object} RequiredArguments
 * @param {string} RequiredArguments.timeSince - Beginning date for the range...
 * @param {string} RequiredArguments.timeUntil - End date for the range...
 */
/**
 * @param {RequiredArguments} paramsss
 * @param {Object} options { filterUserId, filterCustomerId ... }
 */

    I could move this comment to a different issue if it helps.

  8. azu (azu)
    added 2 commits that reference this issue on Dec 30, 2018

    fix(todo): JSDocのdestructuringの記法を修正

    06776ba

    feat(todo): Todoアプリの課題を追加 (#620)

    86a7ceb

  9. sandersn commented on Jan 31, 2019

    @sandersn
    Nathan Shively-Sanders (sandersn)
    on Jan 31, 2019
    Member

    #11859 is just for Typescript, but is otherwise the same. Let's use this issue to track bugs in the Javascript side.

  10. Ryan Cavanaugh (RyanCavanaugh)
    modified the milestones: Community, Backlog on Mar 7, 2019

  11. lookuh commented on Apr 7, 2020

    @lookuh
    lookuh
    on Apr 7, 2020

    Interestingly, both the typedef and the integrated properties syntax work if you declare the argument you're destructuring to be a @property instead of the @param that it is.

  12. 3 remaining items

  13. Juanpam commented on Sep 20, 2021

    @Juanpam
    Juan Pablo Méndez Nogales (Juanpam)
    on Sep 20, 2021

    Jems (@J3m5) I agree! Just my workaround for this issue. Still hoping this gets reviewed soon.

  14. kolchurinvv commented on May 9, 2022

    @kolchurinvv
    Vladimir Kolchurin (kolchurinvv)
    on May 9, 2022

    having the same issue with in vscode in javascript using a named parameter
    custom error class jsdoc

  15. ShadowLNC commented on Jul 22, 2022

    @ShadowLNC
    Scott Stevens (ShadowLNC)
    on Jul 22, 2022

    I seem to have the same issue but I am not specifying my types in JSDoc because I'm explicitly specifying them on the function, e.g.:

    /**
 * Description.
 *
 * @param arg0 arguments.
 * @param arg0.a first.
 * @param arg0.b second.
 * @param arg0.c third.
 */
public async myFunc({a, b, c}: SomeInterface) {}

    Apologies if this is not intended to be supported, the JSDoc docs only show examples where the types are in JSDoc (for object destructuring), but I know that VSCode does display the tooltip for regular parameters even when I don't put types in JSDoc.

  16. PoulBak commented on Aug 8, 2022

    @PoulBak
    PoulBak
    on Aug 8, 2022

    Is JSDoc dead? This is not solved after more than 4 years.

  17. joesawa commented on Jan 26, 2023

    @joesawa
    Joseph Sawa (joesawa)
    on Jan 26, 2023

    Problem still persists into 2023.

  18. dagadbm commented on Jan 30, 2023

    @dagadbm
    David (dagadbm)
    on Jan 30, 2023

    I have found the simplest cleanest solution for this mess.

    /**
 * Main entrypoint and recommended function to use for route navigation.
 * @param {string} location - The path or url to navigate to, serves as a fallback url when goBack is true
 * @param {object} [config] - Additional configuration to alter the navigation
 * @property {object} [config]
 * @param {boolean} [config.replace] - If true, will use replace instead of push. This bypasses the browser history mechanism.
 * @param {boolean} [config.newTab] - If true, will open the url in a new tab, using window.open bypassing router
   * navigation.
 * @param {function} [config.callback] - If a function, will be called after navigation has ended
 * @param {boolean} [config.goBack] - If true, will use the browser history mechanism to go back. If going back leaves
 * the page, e.g. triggers beforeunload event, we warn the user, if he wants to stay in the page we redirect to the
 * provided url, which serves as a fallback.
 */

    image

  19. kolchurinvv commented on Jan 30, 2023

    @kolchurinvv
    Vladimir Kolchurin (kolchurinvv)
    on Jan 30, 2023

    David (@dagadbm) At least there's some work-around. It still doesn't seem to cut it for me, though. take a look:

    export class ExtendedPromiseError extends Error {
  /**
   * `val: "default"` assigns `this.val = val(){return {}}`\
   * you can also assign any value to this prop
   *
   * @param {String} message - required by the parent `Error` class
   * @param {object} options - optional
   * @param {string} [options.cause] - specific reason
   * @param {string|any}  [options.val] - for cases when handler needs to return a value
   * @param {string} [options.once] - if attaching a listener is undesirable
   */
  constructor(message, options) {
    super(message)
    this.message = message
    this.name = "Extended Promise Error"
    this.cause = options?.cause
    if (options?.val) {
      if (options.val === "default") {
        this.val = () => {
          return {}
        }
      } else {
        this.val = options.val
      }
    }
  }
}

    Screenshot 2023-01-30 at 13 55 40

    is there a jsconfig.js / tsconfig.ts setting i'm missing/misusing?

  20. dagadbm commented on Jan 30, 2023

    @dagadbm
    David (dagadbm)
    on Jan 30, 2023

    You are missing the empty line I added with the Property part.

  21. kolchurinvv commented on Jan 30, 2023

    @kolchurinvv
    Vladimir Kolchurin (kolchurinvv)
    on Jan 30, 2023

    that was dumb of me 🤣 - worked like a charm! 💯

  22. joesawa commented on Feb 2, 2023

    @joesawa
    Joseph Sawa (joesawa)
    on Feb 2, 2023

    I have found the simplest cleanest solution for this mess.

    /**
 * Main entrypoint and recommended function to use for route navigation.
 * @param {string} location - The path or url to navigate to, serves as a fallback url when goBack is true
 * @param {object} [config] - Additional configuration to alter the navigation
 * @property {object} [config]
 * @param {boolean} [config.replace] - If true, will use replace instead of push. This bypasses the browser history mechanism.
 * @param {boolean} [config.newTab] - If true, will open the url in a new tab, using window.open bypassing router
   * navigation.
 * @param {function} [config.callback] - If a function, will be called after navigation has ended
 * @param {boolean} [config.goBack] - If true, will use the browser history mechanism to go back. If going back leaves
 * the page, e.g. triggers beforeunload event, we warn the user, if he wants to stay in the page we redirect to the
 * provided url, which serves as a fallback.
 */
    image

    Sadly this leaves out type information.

  23. dagadbm commented on Feb 2, 2023

    @dagadbm
    David (dagadbm)
    on Feb 2, 2023 via email

  24. woodjs commented on May 1, 2023

    @woodjs
    woody (woodjs)
    on May 1, 2023

    My decision

    /**
 * Middleware для загрузки файлов
 * @param {{
 *  allowedExtensions: string[];
 *  compress?: boolean;
 *  directory?: string;
 * }} options - Data Object
 * @param directory - Папка, в которую будут загружаться файлы (по умолчанию: uploads)
 * @param allowedExtensions - Расширения файлов, которые разрешены для загрузки (по умолчанию: ['jpg', 'jpeg', 'png', 'gif'])
 * @param compress - Сжимать ли файлы (по умолчанию: false)
 * @returns {function} - Middleware для загрузки файлов
 */

  25. dmrickey commented on Jun 22, 2023

    @dmrickey
    dmrickey
    on Jun 22, 2023

    This is still an issue. The official jsdoc gives this example

    /**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

    Found here https://jsdoc.app/tags-param.html#parameters-with-properties
    subheader - Documenting a destructuring parameter

    I'd expect the tooltip to work if the jsdoc is correct per its own documentation

  26. jpc-ae commented on Sep 26, 2023

    @jpc-ae
    Jason P. Cochrane (jpc-ae)
    on Sep 26, 2023

    I'm unsure if this could be related to the issue, but I noticed that semicolons are being added instead of commas to object parameters. This happens regardless of using the dot-notation or object definition syntax.

    image

    That is, both of the following result in the above tooltip:

    /**
   * Space object stores snippet groupings in buckets.
   * @param {{name: string, synced: boolean, data: DataBucket}} params
   */
    /**
   * Space object stores snippet groupings in buckets.
   * @param {Object} params
   * @param {string} params.name
   * @param {boolean} params.synced
   * @param {DataBucket} params.data
   */

    I wasn't able to find where this semicolon is being added in the jsdoc parser, but could someone please fix that at least?

  27. Genroa commented on Oct 13, 2023

    @Genroa
    Genroa
    on Oct 13, 2023

    Bumping up this. It's a major issue. Destructured parameters have been around since ES6, and JSDoc has an official documentation on how to document them properly. They're used everywhere, why was it never properly supported in VSCode's JSDoc tooltips?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    BugA bug in TypeScriptDomain: JSDocRelates to JSDoc parsing and type generationHelp WantedYou can do this

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions