docs: add support for multiple signatures

[ST-DDT]

Currently, we only show the first signature of a method.
This results in incomplete information being see below for an example.

I considered these options:

• Switch to the last at that is usually the most accurate one
• Display them all. The only questions is: How?

This involves the following questions:

• Which values should we show in the parameter table and the return statement
• Should we include them in the generated example section somehow?

This issue is here to discuss this.

---

Here is the only method that does use multiple signatures at this point in time:

faker/src/random.ts

Lines 174 to 185 in 60d3cc5

	objectElement<T extends Record<string, unknown>, K extends keyof T>(
	object: T,
	field: 'key'
	): K;
	objectElement<T extends Record<string, unknown>, K extends keyof T>(
	object: T,
	field?: unknown
	): T[K];
	objectElement<T extends Record<string, unknown>, K extends keyof T>(
	object = { foo: 'bar', too: 'car' } as unknown as T,
	field = 'value'
	): K | T[K] {

And it does kind of show up wrong:
https://fakerjs.dev/api/random.html#objectElement

Originally posted by @ST-DDT in #574 (comment)

[Shinigami92]

For now, get with the last one.
Sidenote: "Overloading" is only a concept of TypeScript but not JavaScript.

[Shinigami92]

This PR is here to prevent me accidentally breaking the docs generation, not fixing issues that it currently has.

But this is not a PR?

[ST-DDT]

This PR is here to prevent me accidentally breaking the docs generation, not fixing issues that it currently has.

But this is not a PR?

Yeah, I forgot to remove that line when opening this issue.

[xDivisionByZerox]

Isn't this kinda obsolete/low priority since this will be deprecated in v6.2 by #503?

[ST-DDT]

Well, the methods with formats might benefit from multiple signatures e.g. by limiting the return type to the exact match.
Not sure how many method we have with these though.

faker/src/time.ts

Lines 24 to 26 in a205c07

	recent(
	format: LiteralUnion<'abbr' | 'date' | 'wide' | 'unix'> = 'unix'
	): string | number | Date {

[ST-DDT]

It looks like it isn't that simple.
Typedoc does not detect all/the last signature and it does only add the comments to the first one.
I will try to debug that.

[Shinigami92]

It looks like it isn't that simple. Typedoc does not detect all/the last signature and it does only add the comments to the first one. I will try to debug that.

So we need to open a PR at TypeDoc?