docs: add remarks about external sources

[Shinigami92]

This PR introduces a new JSDoc tag we can use to mark methods depending on external resources not in control of FakerJS itself.

---

I looked up for several possible JSDoc tags and found @remarks to be the one that potentially fits the best. Sadly it is not standardized but at least its listed and used already in some other Projects out there.
ChatGPT also told me after a quick chat that it is one of the best options.

[netlify]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	2adbabe
🔍 Latest deploy log	https://app.netlify.com/projects/fakerjs/deploys/685044e13e3be50008d493cd
😎 Deploy Preview	https://deploy-preview-3452.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.97%. Comparing base (1726ded) to head (2adbabe).
Report is 1 commits behind head on next.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #3452      +/-   ##
==========================================
- Coverage   99.97%   99.97%   -0.01%     
==========================================
  Files        2880     2880              
  Lines      220510   220510              
  Branches      952      952              
==========================================
- Hits       220457   220455       -2     
- Misses         53       55       +2     

Files with missing lines	Coverage Δ
src/modules/image/index.ts	100.00% <ø> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Shinigami92]

@matthewmayer as you are mostly involved in the docs right now, would you like to leave some feedback?

[matthewmayer]

Do you intend this to be surfaced in the web docs?

[Shinigami92]

Do you intend this to be surfaced in the web docs?

On the long run yes 👍
But maybe I need help for that, or someone can help us implementing it there in the doc gen.
For now I would just introduce the baseline for this "feature"

[matthewmayer]

Perhaps add a description of what the tag is used for to https://github.com/faker-js/faker/blob/next/CONTRIBUTING.md#jsdocs

[Shinigami92]

Perhaps add a description of what the tag is used for to https://github.com/faker-js/faker/blob/next/CONTRIBUTING.md#jsdocs

Good idea, I will try to add that in next few days

[Shinigami92]

@matthewmayer Added contribution docs and more remarks to the JSDocs (potentially all, but I'm also just a human and might have missed one 😹)

[xDivisionByZerox]

I've added some web facing documentation extensions.

I've also renamed the tag to the singular form "remark" in 627a681. I found it was more reflecting the actual use case and allows the tag to be included multiple times (if so desired). If you do not agree with this change, feel free to bring forward your concerns.

[Shinigami92]

I've also renamed the tag to the singular form "remark" in 627a681. I found it was more reflecting the actual use case and allows the tag to be included multiple times (if so desired). If you do not agree with this change, feel free to bring forward your concerns.

As we are already not using a standardized tag anyway, these are some really good arguments 👍

[matthewmayer]

Do you think this tag would also be appropriate on the faker.internet.email and faker.phone.number methods to indicate that these may generate emails/phone numbers which belong to real people, so one shouldn't send emails or phone numbers to them.

I think we mention that elsewhere in the documentation but not directly on these methods.

[Shinigami92]

Do you think this tag would also be appropriate on the faker.internet.email and faker.phone.number methods to indicate that these may generate emails/phone numbers which belong to real people, so one shouldn't send emails or phone numbers to them.

I think we mention that elsewhere in the documentation but not directly on these methods.

I'm not sure if we should do this. Thoughts I have about this are:

• start small, do not overuse
• we do not use it for image.personPortrait as this is in our control

however, if others agree with you @matthewmayer, I wont block that decision 🙂