@type does not work on functions

[MattIPv4]

trafficstars

Input code

(Minimal repro: https://github.com/MattIPv4/jsdoc-method-type)

Working, without @type: a.js

/**
 * Test global a
 *
 * @param {string} one
 * @param {number} two
 * @returns {string}
 */
const globalA = (one, two) => one.repeat(two);

/**
 * Test module a
 *
 * @module
 *
 * @param {string} one
 * @param {number} two
 * @returns {string}
 */
module.exports = (one, two) => one.repeat(two);

Not working, using @type: b.js

/**
 * @typedef {function} B
 * @param {string} one
 * @param {number} two
 * @returns {string}
 */

/**
 * Test global b
 *
 * @type {B}
 */
const globalB = (one, two) => one.repeat(two);

/**
 * Test module b
 *
 * @module
 * @type {B}
 */
module.exports = (one, two) => one.repeat(two);

JSDoc configuration

Default.

JSDoc debug output

jsdoc src --debug

DEBUG: JSDoc 3.6.10 (Tue, 25 Jan 2022 02:05:39 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":[],"recurseDepth":10,"source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":"(^|\\/|\\\\)_"},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"templates":{"monospaceLinks":false,"cleverLinks":false,"default":{"outputSourceFiles":true}}},"opts":{"_":["src"],"debug":true,"destination":"./out/","encoding":"utf8"}}}
DEBUG: Parsing source files: ["/Users/mattcowley/WebstormProjects/jsdoc-method-type/src/a.js","/Users/mattcowley/WebstormProjects/jsdoc-method-type/src/b.js"]
Parsing /Users/mattcowley/WebstormProjects/jsdoc-method-type/src/a.js ...
Parsing /Users/mattcowley/WebstormProjects/jsdoc-method-type/src/b.js ...
DEBUG: Finished parsing source files.
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Finished running in 0.20 seconds.

Expected behavior

I would expect @type to behave as the documentation implies, applying the type provided from the typedef to the function.

This would result in the jsdoc output for b.js in the above being almost identical to the jsdoc output for a.js (expect for the naming differences).

Current behavior

When @type is used, the type definition provided is not applied to the function, resulting in the function behaving as if it is undocumented.

a.js	b.js

The @typedef is detected correctly though, just not applied via @type:

Your environment

Software	Version
JSDoc	3.6.10
Node.js	16.14.0
npm	8.3.1
Operating system	macOS 12.3

[tomaszcoding]

I have a similar problem. The thing is that JSDoc was designed to support OO JavaScript and if you use more functional approach it's quite hard to document your code with it.

In your case @typedef won't work, because it is designed to describe a class/prototype and your globalB is not a constructor but a regular function which returns a string value. JSDoc expects that you use globalB with new, which creates an instance of type globalB. That's at least how I understand it.

What we need would be something like @functiondef which would let us describe the function signature and, say @signature <FunctionDef> to "decorate" our function implementations.

[fimion]

i think this is what @callback is for.

[episage]

This might not help generate JSDOC but I found that /** @type {ReturnType<YourFactoryFunction>} */ works for autocompletion in VS Code.

[ronald-mz]

From the looks of it y'all are using VSCode.

VsCode only supports a subset of jsdoc, which is the same subset that Typescript supports.

You can see which types are supported over here: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

If you do a function definition in VSCode, you're going to have to use @callback, https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param

[nyngwang]

@MattIPv4 Did you find a workaround for it? I also wondering whether there is a better doc-generator for TypeScript. While JSDoc is still maintained, I found that so many years-old issues like this one are still open without a clear conclusion.