Typescript: 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 https://github.com/types/npm-pug/pull/5#discussion_r78636341.

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: https://github.com/Microsoft/TypeScript/issues/3294

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

[goodmind]

Any progress?

[MichaelTontchev]

Definitely would love to see this implemented somehow. A function with 3 overloaded type definitions needs copy/paste for all three... not fun...

[goodmind]

@MichaelTontchev you mean that you can define overload now and it will work but with more copy-paste? can you show?

[joma74]

Case here is a es5 class with a method member that is a candidate for method overloading. Using union types this member can be described as

/**
 * @todo See https://github.com/Microsoft/TypeScript/issues/407
 * 
 * @param {string} name 
 * @param {Function | BUFFERTYPE } [content]
 * @param {string} [type]
 * @return {Function | void}
 */
Runtime.prototype.createAttachment = function(name, content, type) {
...

In case of a Function for content, it should return a Function. In case of a BUFFERTYPE for content, it should return void.

Suggestion 1
Make overloaded definition in external d.ts(not on runtime.d.ts).
_P.S. Tried to apply it on the js es5 class level or member method level, but found not way to accomplish that._

Suggestion 2
Make overload list definition in three comment blocks.

/**
 * @param {string} name 
 * @param {Function} [content]
 * @param {string} [type]
 * @return {Function}
 */
/**
 * @param {string} name 
 * @param {BUFFERTYPE} [content]
 * @param {string} [type]
 * @return {void}
 */
Runtime.prototype.createAttachment = function(name, content, type) {
...

_P.S. Tried to apply it on the member method level, but only the first was considered by TS as method signature._

[Igmat]

@mhegazy what kind of _feedback_ is missing?

IMO, everything is pretty straightforward:

export function A(a: string): string;
export function A(a: number): string;
/**
 * Overloaded comment only for this signature
 * @description overloaded description only for this signature
 */
export function A(a: string, b: string): string;
/**
 * @param b overloaded description for `b` argument only for this signature
 * @returns overloaded description for `return` only for this signature
 */
export function A(a: string, b: number): string;
export function A(a: number, b: string): string;
export function A(a: number, b: number): string;
/**
 * Default comment for function A
 * @description default description for A
 * @param a default description for `a` argument
 * @param [b] default description for `b` argument 
 * @returns default comment for `return`
 */
export function A(a: string | number, b?: string | number): string {
    // implementation
}

So, each time when JSDoc is shown, it should merge default docs (that came from implementation in case of .ts file, or from most generic overload in case of .d.ts file) with docs that belong to particular overload, where last one takes precedence.

[captain-yossarian]

Does anybody working on it?

[greaterking]

I'm curious as well.

[webOS101]

Ran into this one, too. Cascading down the first description would be the best, I think. Would greatly reduce the size of .d.ts files that document overloaded functions (In my case, curried functions).

[seahindeniz]

Check this gist. It may give you an idea https://gist.github.com/seahindeniz/4de7ad774c1043ddb47b4080667bb06a

[sandersn]

Complicating things even further, the new @deprecated tag would be ambiguous if appearing on the first signature; overloads are sometimes deprecated individually, but it's also common to deprecate an entire function.

As of the 4.0 beta, quick info says a function is deprecated if -- and only if -- the first signature has @deprecated. But the checker says a function is deprecated if any signature is deprecated. This is likely to change, but it illustrates how hard it is to find the correct behaviour.