Improve documentation of return values

[Shinigami92]

As a user it was not instantly clear to me that the return value of a method like faker.date.past() returns a Date and not a string by just reading the docs @example tag.

---

Proposal:

Change return value comments

- // '2022-02-05T09:55:39.216Z'
+ // Date('2022-02-05T09:55:39.216Z')

Reason: This is actually executable and will indicate clearly that is not just a string

Also change the description to mention {@link Date} instance

---

Attention: We need to update also our documentation generator scripts

[xDivisionByZerox]

It might be interesting that JS itself prints dates by omitting the quotes around the "date string".

This would look like this:
faker.date.past(); // 2022-02-05T09:55:39.216Z

Since we try to comply with other JS standards as well, I'd like to at least discuss this style.

[Shinigami92]

I also found that out (accidentally) a few weeks ago
I think we should do that 👍

[xDivisionByZerox]

So, do we still need to discuss this? If we do id add the needs: discussion label. If we want to go with the JS Date format, I'd add the good first issue label.

[xDivisionByZerox]

Team Decision

We do not see the advantage of this change right now.
TypeScript is already giving sufficent feedback about the return type of date functions. Additionally, when looking at the examples in the documentation, the return type is mentioned directly above.