Overload docs in interface aren't correctly inherited in concrete implementations

[manticorp]

Search terms

overload, interface

Expected Behavior

Overloaded functions in concrete class implementations should inherit the correct documentation from the interface

Actual Behavior

It seems as if only the first overload in the interface gets inherited to all overloads in the concrete implementation

Steps to reproduce the bug

Here is a gist

(note you don't need the abstract class, it occurs with just the interface and concrete)

Here is some minimal code:

interface Test {
  /**
   * Provide a string and I will give you a boolean
   *
   * @example
   * concrete.myFunc('str'); // false
   */
  myFunc (a: string) : boolean;

  /**
   * Pass me a number and I will give you a number
   *
   * @example
   * concrete.myFunc(5); // 1
   */
  myFunc (a: number) : number;


  /**
   * Pass me a string and I will give you a number
   *
   * @example
   * concrete.myFunc('str'); // 1
   */
  anotherFunc (a: string) : number;

  /**
   * Pass me a number and I will give you a boolean
   *
   * @example
   * concrete.myFunc(5); // false
   */
  anotherFunc (a: number) : boolean;
}

class ConcreteTest implements Test {
  myFunc (a: string) : boolean;
  myFunc (a: number) : number;
  myFunc (a: string | number): number | boolean {
    if (typeof a === 'string') {
      return false;
    }
    return 1;
  }

  anotherFunc (a: string) : number;
  anotherFunc (a: number) : boolean;
  anotherFunc (a: string | number): number | boolean {
    if (typeof a === 'string') {
      return 1;
    }
    return false;
  }
}

Here is the result - in the interface, the docs are correct:

But in the concrete implementation, the docs are incorrect:

Environment

• Typedoc version: 0.26.10
• TypeScript version: 5.6.3
• Node.js version: 20.13.1
• OS: Windows

[manticorp]

Here is another, less abstract example, where this fails - although this is slightly difference, with only a single line for the concrete implementation (as they all return a number):

interface DiceInterface {
  n: number,
  d: number,
  plus: number,
}

interface DiceRollerInterface {
  /**
   * Given a string dice representation, roll it
   * @example
   *
   * rng.dice('1d6');
   * rng.dice('3d6+10');
   * rng.dice('1d20-1');
   * rng.dice('d10');
   *
   * @param dice e.g. 1d6+5
   * @return A random roll on the dice
   */
  roll (dice: string): number;

  /**
   * Roll "n" x "d" sided dice and add "plus"
   * @example
   *
   * rng.dice(1, 6);
   * rng.dice(3, 6, 10);
   * rng.dice(1, 20, -1);
   * rng.dice(1, 10);
   *
   * @param  n    The number of dice to roll
   * @param  d    The number of faces on the dice
   * @param  plus The number to add at the end
   * @return A random roll on the dice
   */
  roll (n: number, d?: number, plus?: number): number;

  /**
   * Given an object representation of a dice, roll it
   * @example
   *
   * rng.dice({ d: 6 });
   * rng.dice({ n: 3, d: 6, plus: 10 });
   * rng.dice({ n: 1, d: 20, plus: -1 });
   * rng.dice({ n: 1, d: 10 });
   *
   * @param dice {n, d, plus} format of dice roll
   * @return A random roll on the dice
   */
  roll (dice: DiceInterface): number;

  /**
   * Pass an array of numbers, which are n, d and plus.
   *
   * Roll "n" x "d" sided dice and add "plus"
   *
   * @param  numbers The number of dice to roll, sides of the dice, and plus - defaults are 1, 6, 0
   * @return A random roll on the dice
   */
  roll (numbers: number[]): number;
}

class DiceRoller implements DiceRollerInterface {
  public roll (n: string | DiceInterface | number | number[] = 1, d: number = 6, plus: number = 0): number {
    if (Array.isArray(n)) {
      [n, d, plus] = n;
      return this.roll(n, d, plus)
    }

    if (typeof n === 'string') {
      ({n, d, plus} = this.parseDiceString(n));
      return this.roll(n, d, plus)
    }

    if (typeof n === 'object') {
      ({n, d, plus} = n);
      return this.roll(n, d, plus);
    }

    let result = 0;
    for (let i = 0; i < n; i++) {
      result += 1 + Math.floor(Math.random() * d);
    }
    return result + plus;
  }

  public parseDiceString(str: string) : DiceInterface {
    const diceRe: RegExp = /^ *([0-9]*) *[dD] *([0-9]+) *([+-]? *[0-9]*) *$/;
    const result = diceRe.exec(str.replace(/ +/g, ''));
    if (result !== null) {
      return {
        n: parseInt(result[1]),
        d: parseInt(result[2]),
        plus: parseFloat(result[3]),
      };
    }
    throw new Error(`Could not parse dice string ${str}`);
  }
}

Again, the interface has all the methods documented correctly:

But the concrete implementation has only the docs for one overload:

[Gerrit0]

Here is another, less abstract example, where this fails - although this is slightly difference, with only a single line for the concrete implementation (as they all return a number):

class DiceRoller implements DiceRollerInterface {
 public roll (n: string | DiceInterface | number | number[] = 1, d: number = 6, plus: number = 0): number {

This one is working as expected. TypeDoc is documenting the type that is available to users of your class, which is different (though assignable to) the interface.

new DiceRoller().roll([1, 2, 3], 123) /// Does not conform to interface, but ok