From 18bbc3af75119fb73aba09facf24f163fc36293e Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Tue, 31 Oct 2023 23:27:33 +0100
Subject: [PATCH] docs(phone): improve deprecation and see message (#2517)

---
 src/modules/phone/index.ts | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/modules/phone/index.ts b/src/modules/phone/index.ts
index b677ec4a6b8..448cdf784f8 100644
--- a/src/modules/phone/index.ts
+++ b/src/modules/phone/index.ts
@@ -17,6 +17,9 @@ export class PhoneModule {
   /**
    * Generates a random phone number.
    *
+   * @see faker.string.numeric(): For generating a random string of numbers.
+   * @see faker.helpers.fromRegExp(): For generating a phone number matching a regular expression.
+   *
    * @example
    * faker.phone.number() // '961-770-7727'
    *
@@ -28,13 +31,16 @@ export class PhoneModule {
    *
    * @param format Format of the phone number.
    *
+   * @see faker.string.numeric(): For generating a random string of numbers.
+   * @see faker.helpers.fromRegExp(): For generating a phone number matching a regular expression.
+   *
    * @example
    * faker.phone.number('501-###-###') // '501-039-841'
    * faker.phone.number('+48 91 ### ## ##') // '+48 91 463 61 70'
    *
    * @since 7.3.0
    *
-   * @deprecated Use `faker.phone.number()` without an argument instead.
+   * @deprecated Use `faker.phone.number()` without an argument, `faker.string.numeric()` or `faker.helpers.fromRegExp()` instead.
    */
   number(format: string): string;
   /**
@@ -42,6 +48,9 @@ export class PhoneModule {
    *
    * @param format Format of the phone number. Defaults to a random phone number format.
    *
+   * @see faker.string.numeric(): For generating a random string of numbers.
+   * @see faker.helpers.fromRegExp(): For generating a phone number matching a regular expression.
+   *
    * @example
    * faker.phone.number() // '961-770-7727'
    *
@@ -52,7 +61,8 @@ export class PhoneModule {
     if (format != null) {
       deprecated({
         deprecated: 'faker.phone.number(format)',
-        proposed: 'faker.phone.number()',
+        proposed:
+          'faker.phone.number(), faker.string.numeric() or faker.helpers.fromRegExp()',
         since: '8.1',
         until: '9.0',
       });