JsDoc for overloads

[danmarshall]

When adding JSDoc to an overloaded function, It seems that the JSDoc comment must immediately precede the actual function. When preceding the list of overloads, the JSDoc comment is dropped after compilation.

Example:

module app {

/**
 * Returns "foo"
 * 
 * this doesn't output.
 */
export function foo(x: string): string;
export function foo(x: number): string;
export function foo(x: any): string {
    return "foo";
}


export function bar(x: string): string;
export function bar(x: number): string;

/**
 * Returns "bar"
 * 
 * this will output. but I don't like my overloads detached.
 */
export function bar(x: any): string {
    return "bar";
}

}

[mhegazy]

Overloads do not get emitted, similar to interfaces; they are only used for compile time checks but do not exist at runtime. Only the function implementation exists. the problem is what happens if you have multiple comments, e.g. one per signature. duplicating does not seem ideal. more over, if the comments were aggregated, there is no way for you to document an overload with different information than the implementation (e.g. to show in .d.ts but not in the .js file).

[danmarshall]

I concur. Perhaps the JsDoc subfeature needs its own documentation page. Would be nice to share this knowledge instead of having to learn by surprise. Thanks :)

[mhegazy]

The general rule is that comments follow a language construct; if that ends up emitted the comment will be emitted, otherwise not. This applies to the .js and .d.ts emit as well.