docs: add remarks about external sources (#3452)

11 files changed, 158 insertions, 1 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c3982b27..c4a843c8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -296,6 +296,11 @@ function foo(options: { test: string }) {
 </tr>
 </table>
 
+> Other JSDoc tags are in use for specific cases.
+
+- `@internal` - If the method is not intended to be used by the end user, e.g. a helper function.
+- `@remark` - If the method depends on external data not being controlled by Faker, e.g. a third-party image provider.
+
 > We use eslint-plugin-jsdoc to test for basic styling and sorting of doc-tags.
 
 This is in place so all JSDoc tags will get sorted automatically, so you don't have to bother with it. This also means that most rules in this section can get auto fixed by the eslint formatter.
diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts
index 91f99d4e..9ae154ca 100644
--- a/docs/.vitepress/components/api-docs/method.ts
+++ b/docs/.vitepress/components/api-docs/method.ts
@@ -2,6 +2,7 @@ export interface ApiDocsMethod {
   readonly name: string;
   readonly deprecated: string | undefined; // HTML
   readonly description: string; // HTML
+  readonly remark: string | undefined; // HTML
   readonly since: string;
   readonly parameters: ApiDocsMethodParameter[];
   readonly returns: string;
@@ -9,7 +10,7 @@ export interface ApiDocsMethod {
   readonly signature: string; // HTML
   readonly examples: string; // HTML
   readonly refresh: (() => Promise<unknown[]>) | undefined;
-  readonly seeAlsos: string[];
+  readonly seeAlsos: string[]; // HTML
   readonly sourcePath: string; // URL-Suffix
 }
 
diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
index 37b44748..4ab876ca 100644
--- a/docs/.vitepress/components/api-docs/method.vue
+++ b/docs/.vitepress/components/api-docs/method.vue
@@ -11,6 +11,7 @@ const { method } = defineProps<{ method: ApiDocsMethod }>();
 const {
   deprecated,
   description,
+  remark,
   since,
   parameters,
   returns,
@@ -145,6 +146,11 @@ function seeAlsoToUrl(see: string): string {
 
     <div v-html="description"></div>
 
+    <div v-if="remark" class="tip custom-block">
+      <p class="custom-block-title">Note</p>
+      <div v-html="remark"></div>
+    </div>
+
     <p v-if="since">
       <em>Available since v{{ since }}</em>
     </p>
diff --git a/eslint.config.ts b/eslint.config.ts
index 55020443..fdc8a4d1 100644
--- a/eslint.config.ts
+++ b/eslint.config.ts
@@ -172,6 +172,12 @@ const config: ReturnType<typeof tseslint.config> = tseslint.config(
   {
     name: 'jsdoc overrides',
     rules: {
+      'jsdoc/check-tag-names': [
+        'error',
+        {
+          definedTags: ['remark'],
+        },
+      ],
       'jsdoc/require-jsdoc': 'off', // Enabled only for src/**/*.ts
       'jsdoc/require-returns': 'off',
       'jsdoc/sort-tags': [
@@ -180,6 +186,7 @@ const config: ReturnType<typeof tseslint.config> = tseslint.config(
           tagSequence: [
             { tags: ['template'] },
             { tags: ['internal'] },
+            { tags: ['remark'] },
             { tags: ['param'] },
             { tags: ['returns'] },
             { tags: ['throws'] },
diff --git a/scripts/apidocs/output/page.ts b/scripts/apidocs/output/page.ts
index a9570309..e557454d 100644
--- a/scripts/apidocs/output/page.ts
+++ b/scripts/apidocs/output/page.ts
@@ -137,6 +137,7 @@ async function toMethodData(method: RawApiDocsMethod): Promise<ApiDocsMethod> {
     description,
     since,
     parameters,
+    remarks,
     returns,
     throws,
     signature,
@@ -158,6 +159,7 @@ async function toMethodData(method: RawApiDocsMethod): Promise<ApiDocsMethod> {
     name,
     deprecated: mdToHtml(deprecated),
     description: mdToHtml(description),
+    remark: remarks.length === 0 ? undefined : mdToHtml(remarks.join('\n')),
     since,
     parameters: parameters.map((param) => ({
       ...param,
@@ -178,6 +180,7 @@ async function toMethodData(method: RawApiDocsMethod): Promise<ApiDocsMethod> {
   return {
     name,
     description: mdToHtml(description),
+    remark: remarks.length === 0 ? undefined : mdToHtml(remarks.join('\n')),
     parameters: parameters.map((param) => ({
       ...param,
       type: param.type.text,
diff --git a/scripts/apidocs/processing/jsdocs.ts b/scripts/apidocs/processing/jsdocs.ts
index 41c1b84a..55dea867 100644
--- a/scripts/apidocs/processing/jsdocs.ts
+++ b/scripts/apidocs/processing/jsdocs.ts
@@ -69,6 +69,10 @@ export function getSeeAlsos(jsdocs: JSDoc): string[] {
   return getTagsFromJSDoc(jsdocs, 'see', true);
 }
 
+export function getRemarks(jsdocs: JSDoc): string[] {
+  return getTagsFromJSDoc(jsdocs, 'remark');
+}
+
 function getOptionalTagFromJSDoc(
   jsdocs: JSDoc,
   type: string
diff --git a/scripts/apidocs/processing/signature.ts b/scripts/apidocs/processing/signature.ts
index c7ae872b..8f6cedcb 100644
--- a/scripts/apidocs/processing/signature.ts
+++ b/scripts/apidocs/processing/signature.ts
@@ -8,6 +8,7 @@ import {
   getDescription,
   getExamples,
   getJsDocs,
+  getRemarks,
   getSeeAlsos,
   getSince,
   getThrows,
@@ -39,6 +40,10 @@ export interface RawApiDocsSignature {
    */
   parameters: RawApiDocsParameter[];
   /**
+   * Additional comments of the signature that are supposed to stand out from the description.
+   */
+  remarks: string[];
+  /**
    * The return type of the signature.
    */
   returns: RawApiDocsType;
@@ -107,6 +112,7 @@ function processSignature(
       description: getDescription(jsdocs),
       since: getSince(jsdocs),
       parameters,
+      remarks: getRemarks(jsdocs),
       returns,
       throws: getThrows(jsdocs),
       signature: getSignatureText(signature),
diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index 6b0a7017..ae4d76fe 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -20,6 +20,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random avatar image url.
    *
+   * @remark This method sometimes generates a random string representing an URL from GitHub by using a random user ID. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @example
    * faker.image.avatar()
    * // 'https://avatars.githubusercontent.com/u/97165289'
@@ -38,6 +40,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random avatar from GitHub.
    *
+   * @remark This method generates a random string representing an URL from GitHub by using a random user ID. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @example
    * faker.image.avatarGitHub()
    * // 'https://avatars.githubusercontent.com/u/97165289'
@@ -92,6 +96,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random avatar from `https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar`.
    *
+   * @remark This method generates a random string representing an URL from cloudflare-ipfs. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @example
    * faker.image.avatarLegacy()
    * // 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/170.jpg'
@@ -116,6 +122,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random image url.
    *
+   * @remark This method generates a random string representing an URL from loremflickr. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @param options Options for generating a URL for an image.
    * @param options.width The width of the image. Defaults to a random integer between `1` and `3999`.
    * @param options.height The height of the image. Defaults to a random integer between `1` and `3999`.
@@ -158,6 +166,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random image url provided via https://loremflickr.com.
    *
+   * @remark This method generates a random string representing an URL from loremflickr. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @param options Options for generating a URL for an image.
    * @param options.width The width of the image. Defaults to a random integer between `1` and `3999`.
    * @param options.height The height of the image. Defaults to a random integer between `1` and `3999`.
@@ -205,6 +215,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random image url provided via https://picsum.photos.
    *
+   * @remark This method generates a random string representing an URL from picsum.photos. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @param options Options for generating a URL for an image.
    * @param options.width The width of the image. Defaults to a random integer between `1` and `3999`.
    * @param options.height The height of the image. Defaults to a random integer between `1` and `3999`.
@@ -284,6 +296,8 @@ export class ImageModule extends ModuleBase {
   /**
    * Generates a random image url provided via https://via.placeholder.com/.
    *
+   * @remark This method generates a random string representing an URL from via.placeholder. Faker is not responsible for the content of the image or the service providing it.
+   *
    * @param options Options for generating a URL for an image.
    * @param options.width The width of the image. Defaults to a random number between 1 and 3500.
    * @param options.height The height of the image. Defaults to a random number between 1 and 3500.
diff --git a/test/scripts/apidocs/__snapshots__/method.spec.ts.snap b/test/scripts/apidocs/__snapshots__/method.spec.ts.snap
index 5a5518e4..35de1f34 100644
--- a/test/scripts/apidocs/__snapshots__/method.spec.ts.snap
+++ b/test/scripts/apidocs/__snapshots__/method.spec.ts.snap
@@ -9,9 +9,11 @@ exports[`method > expected and actual methods are equal 1`] = `
   "methodWithDeprecated",
   "methodWithDeprecatedOption",
   "methodWithExample",
+  "methodWithMultipleRemarks",
   "methodWithMultipleSeeMarkers",
   "methodWithMultipleSeeMarkersAndBackticks",
   "methodWithMultipleThrows",
+  "methodWithRemark",
   "methodWithSinceMarker",
   "methodWithThrows",
   "multiParamMethod",
@@ -83,6 +85,7 @@ exports[`method > processMethodLike(complexArrayParameter) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "resolvedType": {
           "text": "any",
@@ -129,6 +132,7 @@ exports[`method > processMethodLike(defaultBooleanParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -166,6 +170,7 @@ exports[`method > processMethodLike(functionParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -440,6 +445,7 @@ exports[`method > processMethodLike(literalUnionParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "string",
         "type": "simple",
@@ -474,6 +480,7 @@ exports[`method > processMethodLike(methodWithDeprecated) 1`] = `
       "description": "Test with deprecated and see marker.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -544,6 +551,7 @@ exports[`method > processMethodLike(methodWithDeprecatedOption) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -577,6 +585,7 @@ exports[`method > processMethodLike(methodWithExample) 1`] = `
         "test.apidocs.methodWithExample() // 0",
       ],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -595,6 +604,38 @@ exports[`method > processMethodLike(methodWithExample) 1`] = `
 }
 `;
 
+exports[`method > processMethodLike(methodWithMultipleRemarks) 1`] = `
+{
+  "name": "methodWithMultipleRemarks",
+  "signatures": [
+    {
+      "deprecated": undefined,
+      "description": "Test with multiple remark markers.",
+      "examples": [],
+      "parameters": [],
+      "remarks": [
+        "First special text.",
+        "Second special text.",
+        "Thrid special text.",
+      ],
+      "returns": {
+        "text": "number",
+        "type": "simple",
+      },
+      "seeAlsos": [],
+      "signature": "function methodWithMultipleRemarks(): number;",
+      "since": "1.0.0",
+      "throws": [],
+    },
+  ],
+  "source": {
+    "column": -1,
+    "filePath": "test/scripts/apidocs/method.example.ts",
+    "line": -1,
+  },
+}
+`;
+
 exports[`method > processMethodLike(methodWithMultipleSeeMarkers) 1`] = `
 {
   "name": "methodWithMultipleSeeMarkers",
@@ -604,6 +645,7 @@ exports[`method > processMethodLike(methodWithMultipleSeeMarkers) 1`] = `
       "description": "Test with multiple see markers.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -634,6 +676,7 @@ exports[`method > processMethodLike(methodWithMultipleSeeMarkersAndBackticks) 1`
       "description": "Test with multiple see markers and backticks.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -664,6 +707,7 @@ exports[`method > processMethodLike(methodWithMultipleThrows) 1`] = `
       "description": "Test with multiple throws.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -685,6 +729,36 @@ exports[`method > processMethodLike(methodWithMultipleThrows) 1`] = `
 }
 `;
 
+exports[`method > processMethodLike(methodWithRemark) 1`] = `
+{
+  "name": "methodWithRemark",
+  "signatures": [
+    {
+      "deprecated": undefined,
+      "description": "Test with remark marker.",
+      "examples": [],
+      "parameters": [],
+      "remarks": [
+        "This text is special.",
+      ],
+      "returns": {
+        "text": "number",
+        "type": "simple",
+      },
+      "seeAlsos": [],
+      "signature": "function methodWithRemark(): number;",
+      "since": "1.0.0",
+      "throws": [],
+    },
+  ],
+  "source": {
+    "column": -1,
+    "filePath": "test/scripts/apidocs/method.example.ts",
+    "line": -1,
+  },
+}
+`;
+
 exports[`method > processMethodLike(methodWithSinceMarker) 1`] = `
 {
   "name": "methodWithSinceMarker",
@@ -694,6 +768,7 @@ exports[`method > processMethodLike(methodWithSinceMarker) 1`] = `
       "description": "Test with since marker.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -721,6 +796,7 @@ exports[`method > processMethodLike(methodWithThrows) 1`] = `
       "description": "Test with throws.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -778,6 +854,7 @@ exports[`method > processMethodLike(multiParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -805,6 +882,7 @@ exports[`method > processMethodLike(noParamMethod) 1`] = `
       "description": "Test with no parameters.",
       "examples": [],
       "parameters": [],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -842,6 +920,7 @@ exports[`method > processMethodLike(optionalStringParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -929,6 +1008,7 @@ Defaults to \`{ value: 1 }\`.",
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -994,6 +1074,7 @@ exports[`method > processMethodLike(optionsInterfaceParamMethodWithDefaults) 1`]
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -1100,6 +1181,7 @@ exports[`method > processMethodLike(optionsParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -1188,6 +1270,7 @@ exports[`method > processMethodLike(optionsTypeParamMethodWithDefaults) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -1229,6 +1312,7 @@ exports[`method > processMethodLike(recordParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -1266,6 +1350,7 @@ exports[`method > processMethodLike(requiredNumberParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "number",
         "type": "simple",
@@ -1645,6 +1730,7 @@ exports[`method > processMethodLike(stringUnionParamMethod) 1`] = `
           },
         },
       ],
+      "remarks": [],
       "returns": {
         "text": "string",
         "type": "simple",
diff --git a/test/scripts/apidocs/method.example.ts b/test/scripts/apidocs/method.example.ts
index 73632b42..0012f4fa 100644
--- a/test/scripts/apidocs/method.example.ts
+++ b/test/scripts/apidocs/method.example.ts
@@ -448,6 +448,30 @@ export class SignatureTest {
   }
 
   /**
+   * Test with remark marker.
+   *
+   * @remark This text is special.
+   *
+   * @since 1.0.0
+   */
+  methodWithRemark(): number {
+    return 0;
+  }
+
+  /**
+   * Test with multiple remark markers.
+   *
+   * @remark First special text.
+   * @remark Second special text.
+   * @remark Thrid special text.
+   *
+   * @since 1.0.0
+   */
+  methodWithMultipleRemarks(): number {
+    return 0;
+  }
+
+  /**
    * Complex array parameter.
    *
    * @template T The type of the entries to pick from.
diff --git a/test/scripts/apidocs/page.spec.ts b/test/scripts/apidocs/page.spec.ts
index 00fd4da2..bef63806 100644
--- a/test/scripts/apidocs/page.spec.ts
+++ b/test/scripts/apidocs/page.spec.ts
@@ -12,6 +12,7 @@ function newTestMethod(
       {
         deprecated: 'deprecated',
         description: 'description',
+        remarks: [],
         since: 'since',
         parameters: [],
         returns: {