Is there any better, idiomatic way to handle similar overloads?

[ELLIOTTCABLE]

Search terms

overloads, D.R.Y., repetition, linking, resolution

Question

As far as I can tell, at the moment, you have to 'document' each overload separately. At least in my experience, the vast, vast majority of "overloads" have exactly the same "documentation", because they're only minor variations in the order or presence or type of arguments that nonetheless behave the same semantically.

The only way I'm aware of, right now, to get coherent documentation, is something like this:

/**
 * Close over `parameter`, prepending it to any arguments passed to `f`.
 *
 * This is a bit like a poorman's `curry()`:
 *
 * ```ts
 * const multiply = (a, b) => a * b
 * const doubler = partial(multiply, 2)
 *
 * multiply(6, 2) //=> 12
 * ```
 *
 * @param f The function to wrap
 * @typeParam First the type of `f`'s first parameter
 * @param parameter A value to prepend to any arguments used in subsequent calls
 * @typeParam Rest a tuple-type for the rest of `f`'s parameters
 * @typeParam Result the return-type of `f`
 * @return The wrapped version of `f` that will prepend the given argument
 */
export function partial<First, Rest extends unknown[], Result>(
   f: (this: void, first: First, ...rest: Rest) => Result,
   parameter: First,
): (...parameters: Rest) => Result

/**
 * Close over `parameter`, prepending it to any arguments passed to `f`.
 *
 * This is a bit like a poorman's `curry()`:
 *
 * ```ts
 * const multiply = (a, b) => a * b
 * const doubler = partial(multiply, 2)
 *
 * multiply(6, 2) //=> 12
 * ```
 *
 * @param f The function to wrap
 * @typeParam First the type of `f`'s first parameter
 * @param parameter A value to prepend to any arguments used in subsequent calls
 * @typeParam Rest a tuple-type for the rest of `f`'s parameters
 * @typeParam Result the return-type of `f`
 * @return The wrapped version of `f` that will prepend the given argument
 */
export function partial<This, First, Rest extends unknown[], Result>(
   f: (this: This, first: First, ...rest: Rest) => Result,
   parameter: First,
): (this: This, ...parameters: Rest) => Result

export function partial<This, First, Rest extends unknown[], Result>(
   f: (this: This, first: First, ...rest: Rest) => Result,
   parameter: First,
): (this: This, ...parameters: Rest) => Result {
   return function (this: This, ...rest: Rest) {
      return f.call(this, parameter, ...rest)
   }
}

It's just … just so verbose.

Ideally, unless there's already a better solution I'm just not aware of, I'd like to be able to mark overloads either as "don't document separately" or "identical to " or something like that, allowing me to avoid the danger of duplicating documentation and having it get out-of-sync with different developers editing it.

[Gerrit0]

Well, this led me down quite the rabbit hole... TypeDoc used to let you put a comment on the implementation, and would then copy it/parts of it to the visible signatures if they didn't specify a comment themselves. Apparently I broke this ~10 months ago, and nobody noticed... 454740b resolves this, v0.22.4 will include a code fix so that you can put the comment on the implementation and it will be inherited by the real signatures if they don't specify coments.

This isn't the ideal situation. I'd really like to say that @inheritDoc should be used here, but unfortunately that isn't possible with TypeDoc's current implementation... yet another thing I'll look at when implementing TSDoc support (https://github.com/TypeStrong/typedoc/projects/11)

[arogozine]

Is this the issue that prevents documentation from showing up on overloaded arrow functions (when documentation is put on the type that defines the arrow function overloads)?

[Gerrit0]

No, that sounds like a different issue - please open a new issue