docs: fix lost description texts (#836)

Author: ST-DDT

docs/.vitepress/theme/index.css

@@ -2,6 +2,14 @@ table td * {
   display: inline;
 }
 
+table td ul {
+  display: block;
+}
+
+table td ul li {
+  display: list-item;
+}
+
 .nav-bar-title .logo {
   min-height: 2rem;
 }

scripts/apidoc/signature.ts

@@ -301,14 +301,17 @@ function extractDefaultFromComment(comment?: Comment): string {
   if (!comment) {
     return;
   }
-  const text = comment.shortText;
-  if (!text || text.trim() === '') {
+  const text = comment.shortText?.trim();
+  if (!text) {
     return;
   }
-  const result = /(.*)[ \n]Defaults to `([^`]+)`./.exec(text);
+  const result = /^(.*)[ \n]Defaults to `([^`]+)`\.(.*)$/s.exec(text);
   if (!result) {
     return;
   }
+  if (result[3].trim()) {
+    throw new Error(`Found description text after the default value:\n${text}`);
+  }
   comment.shortText = result[1];
   return result[2];
 }

src/internet.ts

@@ -47,7 +47,7 @@ export class Internet {
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param provider The mail provider domain to use. If not specified, a random free mail provider will be chosen.
    * @param options The options to use. Defaults to `{ allowSpecialCharacters: false }`.
-   * @param options.allowSpecialCharacters Whether special characters such as `.!#$%&'*+-/=?^_`{|}~` should be included
+   * @param options.allowSpecialCharacters Whether special characters such as ``.!#$%&'*+-/=?^_`{|}~`` should be included
    * in the email address. Defaults to `false`.
    *
    * @example
@@ -90,7 +90,7 @@ export class Internet {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param options The options to use. Defaults to `{ allowSpecialCharacters: false }`.
-   * @param options.allowSpecialCharacters Whether special characters such as `.!#$%&'*+-/=?^_`{|}~` should be included
+   * @param options.allowSpecialCharacters Whether special characters such as ``.!#$%&'*+-/=?^_`{|}~`` should be included
    * in the email address. Defaults to `false`.
    *
    * @example

src/time.ts

@@ -10,13 +10,15 @@ export class Time {
   /**
    * Returns recent time.
    *
-   * @param format The format to use. Defaults to `'unix'`.
+   * @param format The format to use.
    *
    * - `'abbr'` Return a string with only the time. `Date.toLocaleTimeString`.
    * - `'date'` Return a date instance.
    * - `'wide'` Return a string with a long time. `Date.toTimeString()`.
    * - `'unix'` Returns a unix timestamp.
    *
+   * Defaults to `'unix'`.
+   *
    * @example
    * faker.time.recent() // 1643067231856
    * faker.time.recent('abbr') // '12:34:07 AM'

test/scripts/apidoc/signature.example.ts

@@ -155,11 +155,16 @@ export class SignatureTest {
    * Test with a function parameters (inline types) with defaults.
    *
    * @param a Parameter with signature default.
+   * It also has a more complex description.
    * @param a.value The number parameter.
-   * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
-   * @param b.value The boolean parameter.
+   * @param b Parameter with jsdocs default.
+   *
+   * It also has a more complex description.
+   *
+   * Defaults to `{ value: 1 }`.
+   * @param b.value The number parameter.
    * @param c Parameter with inner jsdocs default.
-   * @param c.value The boolean parameter. Defaults to `2`.
+   * @param c.value The number parameter. It also has a more complex description. Defaults to `2`.
    */
   optionsInlineParamMethodWithDefaults(
     a: { value?: number } = { value: 1 },
@@ -175,9 +180,9 @@ export class SignatureTest {
    * @param a Parameter with signature default.
    * @param a.value The number parameter.
    * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
-   * @param b.value The boolean parameter.
+   * @param b.value The number parameter.
    * @param c Parameter with inner jsdocs default.
-   * @param c.value The boolean parameter. Defaults to `2`.
+   * @param c.value The number parameter. Defaults to `2`.
    */
   optionsTypeParamMethodWithDefaults(
     a: ParameterOptionsTypeA = { value: 1 },
@@ -193,9 +198,9 @@ export class SignatureTest {
    * @param a Parameter with signature default.
    * @param a.value The number parameter.
    * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
-   * @param b.value The boolean parameter.
+   * @param b.value The number parameter.
    * @param c Parameter with inner jsdocs default.
-   * @param c.value The boolean parameter. Defaults to `2`.
+   * @param c.value The number parameter. Defaults to `2`.
    */
   optionsInterfaceParamMethodWithDefaults(
     a: ParameterOptionsInterfaceA = { value: 1 },

test/scripts/apidoc/signature.expected.json

@@ -130,7 +130,7 @@
         "name": "a",
         "type": "{ ... }",
         "default": "{ value: 1 }",
-        "description": "<p>Parameter with signature default.</p>\n"
+        "description": "<p>Parameter with signature default.\nIt also has a more complex description.</p>\n"
       },
       {
         "name": "a.value?",
@@ -141,12 +141,12 @@
         "name": "b",
         "type": "{ ... }",
         "default": "{ value: 1 }",
-        "description": "<p>Parameter with jsdocs default.</p>\n"
+        "description": "<p>Parameter with jsdocs default.</p>\n<p>It also has a more complex description.</p>\n"
       },
       {
         "name": "b.value?",
         "type": "number",
-        "description": "<p>The boolean parameter.</p>\n"
+        "description": "<p>The number parameter.</p>\n"
       },
       {
         "name": "c",
@@ -157,7 +157,7 @@
         "name": "c.value?",
         "type": "number",
         "default": "2",
-        "description": "<p>The boolean parameter.</p>\n"
+        "description": "<p>The number parameter. It also has a more complex description.</p>\n"
       }
     ],
     "returns": "number",