Improve support for @overload tags

[kraenhansen]

Search Terms

overload, overloading, overloads

Problem

With the introduction of "@overload Support in JSDoc" from TypeScript v5.0: https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#overload-support-in-jsdoc
Would it make sense to revisit the decision to "punt [support for overloads] to plugin-space": #2002 (comment)?

When documenting the overloads of a function

/**
 * @overload
 * @example
 * ```
 * print("world");
 * ```
 * @param arg {string} A string
 */

/**
 * @overload
 * @example
 * ```
 * print(123);
 * ```
 * @param arg {number} A number
 */

/**
 * Prints the argument
 * @example
 * ```
 * print(321);
 * print("everyone");
 * ```
 */
export function print(arg: string | number) {
  console.log("Hi " + arg);
}

This is the documentation emitted:

I would love a way to declare the documentation of the two overloads.

Suggested Solution

I imagine that a function with overloads could have common documentation and the separate overloads could have sections under the "common" section.

[Gerrit0]

TypeDoc supports the @overload tag -- In .js files using JSDoc, where TypeScript does.

TypeScript has an equivalent syntax which will produce the overloaded docs that you want:

/**
 * @example
 * ```
 * print("world");
 * ```
 * @param arg A string
 */
export function print(arg: string): void;
/**
 * @example
 * ```
 * print(123);
 * ```
 * @param arg A number
 */
export function print(arg: number): void;
/**
 * Prints the argument
 * @example
 * ```
 * print(321);
 * print("everyone");
 * ```
 */
export function print(arg: string | number): void;
export function print(arg: string | number): void {
  console.log("Hi " + arg);
}

I still think including this in TypeDoc with a divergence from how TypeScript does things is a bad idea.

[kraenhansen]

Thanks for the clarification, it makes sense 👍

My use-case for this was to declare the overload for a function being re-exported as a const (see realm-js/packages/realm-react/src/index.tsx#L175-L197).

But ... we could probably re-arrange our exports to make it easier for TypeDoc to understand.

[Gerrit0]

I believe if you add those comments on the signature, in the implementation of createUseQuery, you should get them showing up in your docs... there's a test case for that feature buried somewhere in the tests. (I think that feature is still around? it caused quite a lot of bugs for a few months, I don't remember right now how that all got resolved...)