JSDoc for methods with multiple signatures

[Evgenus]

First I've thought about union types but they can solve only part of the problem. Original discussion started here. In case codeplex had been abandoned, I copy my question here.

Please take a look at this function. https://github.com/digitalbazaar/forge/blob/master/js/rsa.js#L802-L885 As you can see from comments there are a lot of ways to use it. If I need to make a type definitions for it (actually I do) with JSDoc Intellisense support, then I have to copy general function description like 10 times. This will make my definition 3 times longer than source function and also very hard to modify. In libraries like forge almost all functions have being made that way.

Can you give me some tip about making definitions in such circumstances?

[danquirk]

What alternative would you like to see? You want to have the general description inherited when it's written on any overload? Or only when it's written against the implementation signature? Are argument descriptions inherited?

[Evgenus]

You want to have the general description inherited when it's written on any overload?

Yes. It would be nice.

Or only when it's written against the implementation signature?

I'm troubled about that only when writing definitions. So maybe for implementation it could be left as it is. My opinion is Yes.

Are argument descriptions inherited?

Yes, since there are already union types in jsdoc. Also jsdoc have names for arguments, not only index. I think in the most situations meaning of argument depends on its name and not on type. So if it is possible to show description for argument accordingly to its name, then argument description can be inherited.

[Evgenus]

Fresh thought. Maybe support of JSDoc tags @augments and @borrows will helps.

See https://code.google.com/p/jsdoc-toolkit/wiki/TagReference

[basarat]

Some people have used @see in the past e.g. :

https://github.com/borisyankov/DefinitelyTyped/blob/1ba83dded25175aa1239dd6ad0d6e0c81a3571ab/underscore/underscore.d.ts#L725-L738

[Evgenus]

@basarat @see doesn't help in VS right now. It shows only text of reference. And I can't imagine how to reference function/method with same name.

[basarat]

@see doesn't help in VS right now.

Agreed. Was just mentioning what people had tried. I'd like a @augments and @borrows jsdoc lookup in the language service as well.

[sebastian-lenz]

I've stumbled upon this problem too, copying the same comment to several signatures is not dry and leads to a lot of work and potential left overs when someone forgets to update all comments after some changes.

Some kind of inheritance makes sense to me. I would think of the implementation of a function to be the "root" containing the original comment. All signatures borrow this comment automatically unless it is (partly) overwritten in their own comments.

[blakeembrey]

Surprisingly, I just run into this now. It's certainly surprising, I always assumed it worked automatically without having to duplicate comments. See typed-typings/npm-pug#5 (comment).

I would expect this to be a cascade. The first JSDoc description and params should be copied to the following overloads automatically, except you could override the description/param later on by writing it out explicitly. Is this is a reasonable change? If so, I'd be very interested in a trying to patch it if there's a pointer on where to get started. If only so I can avoid merging hard to maintain workarounds like duplicating documentation.

[mickdekkers]

Related issue: #3294

It would be great if this worked as @blakeembrey described 👌