valid-types erroneously requires "function()" type to always have a return type

[lll000111]

This is about types inside brackets, specifically type {function()}, used e.g. with @Property or @param or @returns.

Expected behavior

A return type should not be necessary on function() types:

In general, but also especially when the return type is "undefined"
"jsdoc3" in particular only writes "function" into the HTML output and ignores the types, so this is doubly useless to have to write the lengthy ":undefined" every time.

Code example:

/**
 * @typedef {object} ExporterOptions
 * @property {function(string)} logSentObject
 * @property {function(Error)} logError - Log Errors
 */

Error message example:

The error disappears when I add ":undefined" to the end of each function type.

exporter.ts
  19:0  error  Syntax error in type: function(string)  jsdoc/valid-types
  20:0  error  Syntax error in type: function(Error)   jsdoc/valid-types

ESLint Config

Config includes 'jsdoc/valid-types': 'error'

Project files are typescript and I set settings.jsdoc.mode to "typescript" (or left it empty as an experiment).

When I set "mode" to "jsdoc" the error disappears.

Environment

• Node version: v16.4.0
• ESLint version v7.29.0
• eslint-plugin-jsdoc version: v35.4.0

[lll000111]

ADDED NOTE

In the README of this project under "check-types"

The following patterns are not considered problems:

I found

/** @param {function(...)} callback The function to invoke. */
var subscribe = function(callback) {};

A function without return type.

The "valid-types" examples only have a function type together with @template in a complex example, but "check-types" should be the same for valid syntax of types.

[lll000111]

Closing while I check it more thoroughly....

[brettz9]

If you can't figure it out, maybe you could try npm update, ensuring node_modules/@es-joy/jsdoccomment is at the latest available: 0.8.0 as it is working in our test environment.

[brettz9]

If that ends up being the problem, please let me know, so I can push the latest which forces that latest version.

[lll000111]

@brettz9

ensuring node_modules/@es-joy/jsdoccomment is at the latest available: 0.8.0

It is "version": "0.8.0",

[lll000111]

@brettz9

I was unsure if this is a bug that I can report when I noticed it's only because of the Typescript. mode: "jsodc" removes the problem. So I was about to check if the eslint-typescript settings had an influence.

However, I don't want to treat the JSDoc types the same as the Typescript annotations. For the latter I do indeed want to have "void" return types annotated and not left out. For the jsdoc I don't see a need though - the IDE gets the types it shows me from the actual TypeScript annotations, and "jsdoc3" which I use to create HTML API docs completely ignores the parameter and return types inside "function()" types. So adding a lot of ":undefined" is just a useless waste of space.

Could I have "void/undefined" return types ignored for JSDoc types regardless of what the Typescript setting is? If that is even used (I have not concluded the experiments).

[brettz9]

Oh, sorry, I hadn't noticed the mode aspect.

Type parser questions/issues should be best directed to our type parser, jsdoc-type-pratt-parser including the behaviors under different modes. We switched to this parser (which probably caused the changes), as it quickly began to support all our old types as well as adding new TypeScript types, while our old type parser project had stalled. The "permissive" mode might allow this and TypeScript, but it might miss reporting you would want in either more specific mode, and there are some edge cases within eslint-plugin-jsdoc not related to type parsing where the choice of permissive behavior in the situation was somewhat unclear as to the best behavior to allow.

[simonseyock]

At the moment the jsdoc-type-pratt-parser tries to only parse valid typescript expressions in typescript mode. But it would easily be possible to pass through a grammar option.

[simonseyock]

You could still use the type function if you don't bother about parameters. But I will look into it to make it optional so the eslint-plugin-jsdoc has the choice what to support.

[lll000111]

@simonseyock I should probably mention I only want to leave it out for "undefined/void" returns. I fill out all the rest, thinking that some day I'll patch that hardly maintained jsdoc3 to not just print "function" and ignore all parameters...

My workaround was to write the entire function header again in the text part — this is not for JSDoc for functions, where the parameters are visible in the HTML output anyway, but for object types and their properties. Example: https://docs.refinio.one/projects/one.core/global.html#ArrayValueMap (see ArrayValueMap property types and descriptions)

[brettz9]

@simonseyock : Maybe consumers could supply a callback for a given type, so we could provide that logic?

If we could provide a callback, perhaps we could allow users to supply JSDoc type AST which, if matching a type (internally we could use esquery.matches) could let it go. But all of this would only be when checking valid typescript, jsdoc, or closure.

@lll000111 : Is there a reason you are not using typedoc for building docs? Is your main reason to be more flexible like this?

[lll000111]

@brettz9 I tried various tools two years ago and found the broken jsdoc3 still the easiest to get what I want out of. None of them were really good. Some day I'll again check the state of the JSDOC-to-HTML-API-doc tools but not now (it would not be a giant leap forward even if it's a little better).

My biggest issue with JSDoc right now is a bug in Webstorm for the last two versions or so where the JSDoc contents is no longer displayed in CTRL-Q info windows, inline documentation available at a mouseover or CTRL-Q being the other purpose of all the comments: https://youtrack.jetbrains.com/issue/WEB-50386 (you can help boost this issue :) )