TypeScript: JSDoc @typedef not working as expected

From @ffxsam on June 29, 2018 16:44

VSCode Version: 1.24.1
OS Version: macOS 10.13.5

@typedef support seems a bit buggy. There are a couple of things going on, but related.

First, typdefs with properties don’t seem to work as expected. I have the following file, funcs.js:

/**
 * API options.
 * @typedef {Object} ApiOptions
 * @property {number} artificialDelay Number of milliseconds for an artificial delay
 * @property {boolean} debug Debug mode
 */

/**
 *
 * @param {string} url URL to call
 * @param {ApiOptions} [options] API options
 */
export function apiCall(url, options = {}) {}

And in index.js, I import apiCall but the JSDoc hints don’t show the properties of ApiOptions:

screen_shot_2018-06-29_at_11_17_05_am__2_

Also, typdefs should be able to be “exportable”. I modified funcs.js to this:

/** @module api */

/**
 * API options.
 * @typedef {Object} module:api.ApiOptions
 * @property {number} artificialDelay Number of milliseconds for an artificial delay
 * @property {boolean} debug Debug mode
 */

/**
 *
 * @param {string} url URL to call
 * @param {module:api.ApiOptions} [options] API options
 */
export function apiCall(url, options = {}) {}

I added a new file called middle.js:

import { apiCall } from './funcs';

/**
 *
 * @param {module:api.ApiOptions} options
 */
export function test(options) {}

VSCode doesn’t seem to understand this usage at all:

screen_shot_2018-06-29_at_11_42_20_am__2_

It would be great if VSCode fully supported this for projects that aren’t using TypeScript.

Does this issue occur when all extensions are disabled?: Yes

Copied from original issue: Microsoft/vscode#53348

About this issue

Original URL
State: closed
Created 6 years ago
Reactions: 2
Comments: 21 (4 by maintainers)

Commits related to this issue

style: Make dummy export really export nothing I vaguely remember seeing this trick in a GitHub issue thread, but I can't recall where. A bit of searching gave me this: https://github.com/microsof... — committed to pastelmind/d2calc by pastelmind 4 years ago

Most upvoted comments

From @Lenophie on June 30, 2018 22:10

What’s weird is Intellisense/VSCode already exports typedef across a project by default BUT it can fail if the custom type uses other custom types. Here are some test cases.

Declaration of CustomType in a file : Declaration of a variable of type CustomType in another file : Quick info works. 👍 Displayed type is correct. 👍 Displayed type property is correct. 👍

Declaration of CustomType using another custom type CustomType2 in a file : Declaration of a variable of type CustomType in another file : Quick info doesn’t work. 👎

Declaration of CustomType using another custom type CustomType2 AND declaration of a variable of type CustomType in the same file : Quick info works. 👍 Displayed type is correct. 👍 Displayed type property is correct. 👍

Declaration of CustomType AND declaration of a variable of type CustomType in the same file BUT declaration of CustomType2 in another file : Quick info works. 👍 Displayed type is correct. 👍 Displayed type property is wrong. 👎

I hope this breakdown of different cases help solve the issue !

mjbvz on Jul 3, 2018

The following works for me, to get a typedef from another file:

/** @typedef {object} EncodeVideox265Options
 * @property {import('./ffprobe').VideoDimensions} dimensions Dimensions of the *original* video.
 * @property {string} source Path to source file.
 * @property {string} target Path to target file.
 */

// file: ffprobe.js
/** @typedef {object} VideoDimensions
 * @property {number} height Height of the video in pixels.
 * @property {number} width Width of the video in pixels.
 */

However, in a different situation, the following doesn’t work despite all typedefs being in the same file:

'use strict';
/**
 * Transcodes a file from the given message.
 * @param {TranscodeMessage} message 
 */
function handleMessage(message) {
  message.payload.?????
}
module.exports = handleMessage;

/** @typedef {object} TranscodeMessage
 * @property {TranscodePayload} payload
 */

/** @typedef {object} TranscodePayload
 * @property {string} service Service name.
 * @property {string} action Action name.
 */

Changing the 2nd examples typedef to use the import('./same-file').TranscodePayload does work:

/** @typedef {object} TranscodeMessage
 * @property {import('./transcode').TranscodePayload} payload
 */

// ...

waynebloss on Jul 12, 2018

Ah, never mind. I was missing the import in my referenes to ApiOptions. Also, it works fine in JS files, but not Vue files, so this is now a Vetur issue.

ffxsam on Jul 19, 2018

here is what i see on typescript@next:

mhegazy on Jul 3, 2018

@ffxsam hey—sorry to hijack, and this has obviously been a while. I’ve been trying to get the exact behavior you’re talking about: the individual options/properties defined inside a typedef to expand automatically inside what VS Code shows in its tooltip. I simply cannot get that behavior to occur. It always seems to require doing the Trigger Suggest keyboard shortcut.

Is this still ‘working’ for you? Is doing something special/particular needed?

chrisaljoudi on Nov 29, 2019

@ffxsam The {module:api.ApiOptions} syntax isn’t supported. Try just @typedef {Object} ApiOptions and reference it with {ApiOptions} (in the same module) or {import("./funcs").ApiOptions} (from a different module).

ghost on Jul 12, 2018