how to [overload] function

[NewFuture]

Hi, I have a problem to declare the overload function.

jscomments:

/**
 * @function 
 * @name f
 * @return {number[]}
 */
/**
 * @function 
 * @name f
 * @param {string} key
 * @return {number}
 */

the result:

/**
 * @function
 * @name f
 * @return {number[]}
 */
declare function f(): number;

expect:

declare function f(): number[];
declare function f(key:string): number;

The JSDOC default template can build both functions

f() → {Array.}
f(key) → {number}

it there any way to do like this?

[englercj]

Ah I think this is because I use the FQN of a function as the key for storing it; so currently there can only be one. Good catch.

[NewFuture]

hi, look here https://github.com/englercj/tsd-jsdoc/blob/master/src/Emitter.ts#L177-L179

I remove those 3 lines and use the @variation as following. It will work correctly

/**
 * @function 
 * @name f
 * @variation 1
 * @return {number[]}
 */
/**
 * @function 
 * @name f
 * @variation 2
 * @param {string} key
 * @return {number}
 */

it will parse as f(1) and f(2)

But I'm not sure whether there is any side effects

[NewFuture]

hi, @englercj
I think it should be filtered by the longname rather than the name , if filter is needed here.

please fix it, thanks~

[englercj]

So there are two issues here.

Firstly, JSDoc will not have 2 declarations for two symbols that have the same longname. In your example, both f functions have the same longname and are therefore combines. Simply adding @variation <something> fixes that.

Secondly, two functions that share the same name in a class or namespace will get deduped by tsd-jsdoc if they have the same name, even if they have different longnames. I have a fix pending for this.

You cannot have two functions with the same name, same longname, but different parameters/return type. That will not work because JSDoc won't give us the information, it will combine the two longnames into one declaration.

[tambien]

Thanks for the great library! Checking out this issue in jsdocs repo (jsdoc/jsdoc#1017), it seems like there is a way to add multiple docs to a single statement by combining the end of one comment block with the beginning of the next.

i was able to get tsd-jsdoc to correctly document an overloaded function by doing something like this:

/**
 *  Test if the argument is a boolean.
 *  @variation 1
 *  @param {boolean} arg the argument to test
 *  @returns {true} true if the arg is a boolean
 *  @static
 *  @memberOf MyClass
 *//**
 *  Test if the argument is a boolean.
 *  @variation 2
 *  @param {*} arg the argument to test
 *  @returns {false} true if the arg is a boolean
 *  @static
 *  @memberOf MyClass
 */

Could this combined syntax alleviate the need to include the @variation tag?

[englercj]

In my experience, no. The variation tag is required. It is up to jsdoc to give us the right info, and I've always had to use @variation in the past, despite what that ticket says.