Support variation of type declaration

[miyasudokoro]

Motivation

I prefer using a variation of param type declaration which both JSDoc and TypeScript parse normally. In this variation, the name of the parameter comes first, then its type, and then its description. Here is an example.

/**
 @param data {salty} database contents as processed by JSDocs -- See <https://github.com/jsdoc/jsdoc/tree/main/packages/jsdoc-salty#use-salty-in-a-jsdoc-template>.
 @param opts {object} the options that were set in a package.json file
 @param [tutorials] {RootTutorial} the nested tutorial information as processed by JSDocs
 */
exports.publish = function( data, opts, tutorials ) {
    const publisher = new Publisher( opts );
    publisher.process( data, tutorials );
};

Current behavior

The rule jsdoc/require-param-type says "Missing JSDoc @param "data" type." (and so forth) even though the type is present, as in the example above.

Desired behavior

The rule should detect the type if it comes after the name.

Alternatives considered

I suppose I could rewrite 10,000+ JSDoc declarations to put the type before the name. For now, I have had to disable this rule.

[brettz9]

I'm afraid that of all the popular variants of JSDoc (the original, Closure, and the TypeScript-flavor), none of them vary the position of the type/name. As such, our comment parsers and tooling all assume this order and don't plan to deviate from these forms.

I would strongly recommend your bulk-replacing your code with some kind of script (ideally using a parser like Babel to find the comment blocks) so that you will be able to take advantage of not just our tooling but JSDoc-based document generators, TypeScript, etc.

(I'd also probably try adding initial line asterisks in the process, as that is pretty commonplace too, being added by IDEs and such, though t is not required.)

Closing but feel free to comment further.

[miyasudokoro]

@brettz9 Thank you for being the bearer of bad news.

The underlying code (currently in file jsdoc/lib/jsdoc/tag/type.js) accepts the type declaration at any location in the tag's text, so JSDocs and TypeScript are both perfectly happy with this variation. I am certain what I do used to be an officially-documented variation, or else I would not have adopted it 10+ years ago.

However, it looks like it's no longer documented, and that means I'm wrong to still be using it. This is unfortunate news for me because I now need to update 100+ repos and retrain all the junior devs.

[brettz9]

Oh, my apologies for the wrong info on TypeScript and JSDoc too, wow. Good info. Am so used to our parsers and the docs, I assumed the inflexibility must be the case. Still, yeah, our tooling assumes the order, and I still really wouldn't want to encourage deviating from what is such a strong norm. Wonder what TSDoc was intending for its planned specification.

My sincere sympathies for your migration issues!