docs: improve lorem jsdocs (#458)

1 files changed, 86 insertions, 28 deletions

diff --git a/src/lorem.ts b/src/lorem.ts
index afbc6df3..f682632b 100644
--- a/src/lorem.ts
+++ b/src/lorem.ts
@@ -1,6 +1,9 @@
 import type { Faker } from '.';
 import type { Helpers } from './helpers';
 
+/**
+ * Module to generate random texts and words.
+ */
 export class Lorem {
   private readonly Helpers: Helpers;
 
@@ -19,8 +22,11 @@ export class Lorem {
   /**
    * Generates a word of a specified length.
    *
-   * @method faker.lorem.word
    * @param length length of the word that should be returned. Defaults to a random length
+   *
+   * @example
+   * faker.lorem.word() // 'temporibus'
+   * faker.lorem.word(5) // 'velit'
    */
   word(length?: number): string {
     const hasRightLength = (word: string) => word.length === length;
@@ -37,8 +43,11 @@ export class Lorem {
   /**
    * Generates a space separated list of words.
    *
-   * @method faker.lorem.words
-   * @param num number of words, defaults to 3
+   * @param num The number of words to generate. Defaults to `3`.
+   *
+   * @example
+   * faker.lorem.words() // 'qui praesentium pariatur'
+   * faker.lorem.words(10) // 'debitis consectetur voluptatem non doloremque ipsum autem totam eum ratione'
    */
   words(num?: number): string {
     if (typeof num == 'undefined') {
@@ -52,11 +61,14 @@ export class Lorem {
   }
 
   /**
-   * sentence
+   * Generates a space separated list of words beginning a capital letter and ending with a dot.
+   *
+   * @param wordCount The number of words, that should be in the sentence. Defaults to a random number between `3` and `10`.
+   * @param range Currently this parameter does nothing.
    *
-   * @method faker.lorem.sentence
-   * @param wordCount defaults to a random number between 3 and 10
-   * @param range
+   * @example
+   * faker.lorem.sentence() // 'Voluptatum cupiditate suscipit autem eveniet aut dolorem aut officiis distinctio.'
+   * faker.lorem.sentence(5) // 'Laborum voluptatem officiis est et.'
    */
   // TODO @Shinigami92 2022-01-11: `range` is not in use
   sentence(wordCount?: number, range?: number): string {
@@ -73,10 +85,12 @@ export class Lorem {
   }
 
   /**
-   * slug
+   * Generates a slugified text consisting of the given number of hyphen separated words.
    *
-   * @method faker.lorem.slug
-   * @param wordCount number of words, defaults to 3
+   * @param wordCount The number of words to generate. Defaults to `3`.
+   *
+   * @example
+   * faker.lorem.slug() // 'dolores-illo-est'
    */
   slug(wordCount?: number): string {
     const words = this.faker.lorem.words(wordCount);
@@ -84,17 +98,23 @@ export class Lorem {
   }
 
   /**
-   * sentences
+   * Generates the given number of sentences.
+   *
+   * @param sentenceCount The number of sentences to generate. Defaults to a random number between `2` and `6`.
+   * @param separator The separator to add between sentences. Defaults to `' '`.
    *
-   * @method faker.lorem.sentences
-   * @param sentenceCount defaults to a random number between 2 and 6
-   * @param separator defaults to `' '`
+   * @example
+   * faker.lorem.sentences() // 'Iste molestiae incidunt aliquam possimus reprehenderit eum corrupti. Deleniti modi voluptatem nostrum ut esse.'
+   * faker.lorem.sentences(2) // 'Maxime vel numquam quibusdam. Dignissimos ex molestias quos aut molestiae quam nihil occaecati maiores.'
+   * faker.lorem.sentences(2, '\n')
+   * // 'Et rerum a unde tempora magnam sit nisi.
+   * // Et perspiciatis ipsam omnis.'
    */
   sentences(sentenceCount?: number, separator?: string): string {
     if (typeof sentenceCount === 'undefined') {
       sentenceCount = this.faker.datatype.number({ min: 2, max: 6 });
     }
-    if (typeof separator == 'undefined') {
+    if (typeof separator === 'undefined') {
       separator = ' ';
     }
     const sentences: string[] = [];
@@ -105,10 +125,13 @@ export class Lorem {
   }
 
   /**
-   * paragraph
+   * Generates a paragraph with at least the given number of sentences.
+   *
+   * @param sentenceCount The minim number of sentences to generate. Defaults to `3`.
    *
-   * @method faker.lorem.paragraph
-   * @param sentenceCount defaults to 3
+   * @example
+   * faker.lorem.paragraph() // 'Non architecto nam unde sint. Ex tenetur dolor facere optio aut consequatur. Ea laudantium reiciendis repellendus.'
+   * faker.lorem.paragraph() // 'Animi possimus nemo consequuntur ut ea et tempore unde qui. Quis corporis esse occaecati.'
    */
   paragraph(sentenceCount: number = 3): string {
     return this.faker.lorem.sentences(
@@ -117,12 +140,29 @@ export class Lorem {
   }
 
   /**
-   * paragraphs
+   * Generates the given number of paragraphs.
    *
-   * @method faker.lorem.paragraphs
-   * @param paragraphCount defaults to 3
-   * @param separator defaults to `'\n \r'`
+   * @param paragraphCount The number of paragraphs to generate. Defaults to `3`.
+   * @param separator The separator to use. Defaults to `'\n \r'`.
+   *
+   * @example
+   * faker.lorem.paragraphs()
+   * // 'Beatae voluptatem dicta et assumenda fugit eaque quidem consequatur. Fuga unde provident. Id reprehenderit soluta facilis est laborum laborum. Illum aut non ut. Est nulla rem ipsa.
+   * // Voluptatibus quo pariatur est. Temporibus deleniti occaecati pariatur nemo est molestias voluptas. Doloribus commodi et et exercitationem vel et. Omnis inventore cum aut amet.
+   * // Sapiente deleniti et. Ducimus maiores eum. Rem dolorem itaque aliquam.'
+   *
+   * faker.lorem.paragraphs(5)
+   * // 'Quia hic sunt ducimus expedita quo impedit soluta. Quam impedit et ipsum optio. Unde dolores nulla nobis vero et aspernatur officiis.
+   * // Aliquam dolorem temporibus dolores voluptatem voluptatem qui nostrum quia. Sit hic facilis rerum eius. Beatae doloribus nesciunt iste ipsum.
+   * // Natus nam eum nulla voluptas molestiae fuga libero nihil voluptatibus. Sed quam numquam eum ipsam temporibus eaque ut et. Enim quas debitis quasi quis. Vitae et vitae.
+   * // Repellat voluptatem est laborum illo harum sed reprehenderit aut. Quo sit et. Exercitationem blanditiis totam velit ad dicta placeat.
+   * // Rerum non eum incidunt amet quo. Eaque laborum ut. Recusandae illo ab distinctio veritatis. Cum quis architecto ad maxime a.'
+   *
+   * faker.lorem.paragraphs(2, '<br/>\n')
+   * // 'Eos magnam aut qui accusamus. Sapiente quas culpa totam excepturi. Blanditiis totam distinctio occaecati dignissimos cumque atque qui officiis.<br/>
+   * // Nihil quis vel consequatur. Blanditiis commodi deserunt sunt animi dolorum. A optio porro hic dolorum fugit aut et sint voluptas. Minima ad sed ipsa est non dolores.'
    */
+  // TODO ST-DDT 2022-02-09: The separator looks odd.
   paragraphs(paragraphCount: number = 3, separator: string = '\n \r'): string {
     const paragraphs: string[] = [];
     for (paragraphCount; paragraphCount > 0; paragraphCount--) {
@@ -132,10 +172,18 @@ export class Lorem {
   }
 
   /**
-   * Returns random text based on a random lorem method
+   * Generates a random text based on a random lorem method.
    *
-   * @method faker.lorem.text
-   * @param times
+   * @param times This parameter does nothing.
+   *
+   * @example
+   * faker.lorem.text() // 'Doloribus autem non quis vero quia.'
+   * faker.lorem.text()
+   * // 'Rerum eum reiciendis id ipsa hic dolore aut laborum provident.
+   * // Quis beatae quis corporis veritatis corrupti ratione delectus sapiente ut.
+   * // Quis ut dolor dolores facilis possimus tempore voluptates.
+   * // Iure nam officia optio cumque.
+   * // Dolor tempora iusto.'
    */
   // TODO @Shinigami92 2022-01-11: `times` is not in use
   text(times?: number): string {
@@ -153,10 +201,20 @@ export class Lorem {
   }
 
   /**
-   * Returns lines of lorem separated by `'\n'`
+   * Generates the given number lines of lorem separated by `'\n'`.
+   *
+   * @param lineCount The number of lines to generate. Defaults to a random number between `1` and `5`.
+   *
+   * @example
+   * faker.lorem.lines()
+   * // 'Rerum quia aliquam pariatur explicabo sint minima eos.
+   * // Voluptatem repellat consequatur deleniti qui quibusdam harum cumque.
+   * // Enim eveniet a qui.
+   * // Consectetur velit eligendi animi nostrum veritatis.'
    *
-   * @method faker.lorem.lines
-   * @param lineCount defaults to a random number between 1 and 5
+   * faker.lorem.lines()
+   * // 'Soluta deserunt eos quam reiciendis libero autem enim nam ut.
+   * // Voluptate aut aut.'
    */
   lines(lineCount?: number): string {
     if (typeof lineCount === 'undefined') {