Proposal: enhance JSDoc deprecate parameter description

[xDivisionByZerox]

Clear and concise description of the problem

As a developer using faker I want to see some intel about a deprecated method in intellisense. This could help me to figure out what I should use instead without waiting for a log that tells me.

Suggested solution

Add meaningful documentation to JSDocs deprecated parameter.

Like:

/**
  * @deprecated
  * Use faker.name.firstName instead.
  * /
faker.name.firstname()

This would result in a more excellent information box resulting and in a better developer experience by not only telling me that a method is deprecated but telling me what I should do instead.
Like:

Alternative

Don't do anything

Additional context

rxjs is doing the same for their operators (just ONE reference)

[ST-DDT]

Should we include that also in our api docs page?

[xDivisionByZerox]

Should we include that also in our api docs page?

I think that would be a great idea. I don't use the API docs TBH so I didn't realize they could be in need of this feature as well.

[import-brain]

Should we include that also in our api docs page?

Yeah, I also think this would be a great idea. It would definitely improve the docs.

[xDivisionByZerox]

Currently, we provide this information via the @see parameter. Would we move this into the @deprecated parameter description and no longer use it (@see) for deprecations?

[import-brain]

Currently, we provide this information via the @see parameter. Would we move this into the @deprecated parameter description and no longer use it (@see) for deprecations?

Yeah, I think it would be more clear if we moved the information to the @deprecated parameter and wrote something like "Use this function instead".

[ST-DDT]

If it generates a clickable link for the docs, sure go for it.

[xDivisionByZerox]

Do you mean in the docs? Because currently there is no link in the JSDoc in my IDE :/

[ST-DDT]

I'm referring to the api docs website:
Example: https://fakerjs.dev/api/address.html#cityPrefix

[Shinigami92]

Here an image, as the link posted above by @ST-DDT will get stale some day

[Shinigami92]

Repeating my message here from: #1067 (comment)

I would say @see => links to the replacement, @Deprecation message => message = a human readable text about what's going on 🤔

[xDivisionByZerox]

This has been resolved by #1067.