JSDoc for methods with multiple signatures

Topics: General
Nov 21, 2013 at 3:15 PM
According to this thread, type information from the JsDoc comments is ignored in favor of the TypeScript type. Does that mean that if one method has multiple signatures, the same JsDoc comment will be shared between them? Or does each method signature need its own JsDoc comment?

It feels that documenting the method in the following way is too redundant:
/**                                                                 
Validates the input
@method
@param input Input element
@returns true if validation passed
*/
validateInput(input: Element): boolean;
/**
Validates the input
@method                                                             
@param input Input element
@returns true if validation passed
*/
validateInput(input: JQuery): boolean;
... however that argument doesn't make sense if the same method has different behavior depending on its arguments (which is arguably a good API, but may exist)
Coordinator
Nov 22, 2013 at 4:19 PM
You've got it - it's intended that each overload would be documented separately. As you point out, this gives you the flexibility to talk about when an overload is doing something different with the input (as might happen in libraries like jQuery), though like you say, this also means that you need to repeat yourself in the cases where the overloads function the same way.
Aug 8, 2014 at 4:31 PM
Hi. jonturner is probably right. This is intended feature. But...

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?
Aug 8, 2014 at 4:40 PM
Indeed, it would be useful if comments from one overload were inherited to others if they don't have more specific ones.