docs: add support for multiple signatures

faker-js / faker

Generate massive amounts of fake data in the browser and node.js

https://fakerjs.dev

Other

12.78k stars 915 forks source link

docs: add support for multiple signatures #592

Closed ST-DDT closed 2 years ago

ST-DDT commented 2 years ago

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: https://github.com/faker-js/faker/blob/60d3cc519cd2cab061a23fbe09164d8b59e177ff/src/random.ts#L174-L185 And it does kind of show up wrong: https://fakerjs.dev/api/random.html#objectElement

_Originally posted by @ST-DDT in https://github.com/faker-js/faker/pull/574#discussion_r818199495_

Shinigami92 commented 2 years ago

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

Shinigami92 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

ST-DDT commented 2 years ago

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.

https://github.com/faker-js/faker/blob/a205c0770c8661ccddf1b9166cbb110e86fc2485/src/time.ts#L24-L26

ST-DDT commented 2 years ago

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 commented 2 years ago

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?