docs: add examples to animal jsdocs (faker-js#417)

Author: ST-DDT

src/animal.ts

@@ -1,5 +1,8 @@
 import type { Faker } from '.';
 
+/**
+ * Module to generate animal related entries.
+ */
 export class Animal {
   constructor(private readonly faker: Faker) {
     // Bind `this` so namespaced is working correctly
@@ -14,6 +17,8 @@ export class Animal {
   /**
    * Returns a random dog breed.
    *
+   * @example
+   * faker.animal.dog() // 'Irish Water Spaniel'
    */
   dog(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.dog);
@@ -22,6 +27,8 @@ export class Animal {
   /**
    * Returns a random cat breed.
    *
+   * @example
+   * faker.animal.cat() // 'Singapura'
    */
   cat(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.cat);
@@ -30,6 +37,8 @@ export class Animal {
   /**
    * Returns a random snake species.
    *
+   * @example
+   * faker.animal.snake() // 'Eyelash viper'
    */
   snake(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.snake);
@@ -38,6 +47,8 @@ export class Animal {
   /**
    * Returns a random bear species.
    *
+   * @example
+   * faker.animal.bear() // 'Asian black bear'
    */
   bear(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.bear);
@@ -46,6 +57,8 @@ export class Animal {
   /**
    * Returns a random lion species.
    *
+   * @example
+   * faker.animal.lion() // 'Northeast Congo Lion'
    */
   lion(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.lion);
@@ -54,7 +67,8 @@ export class Animal {
   /**
    * Returns a random cetacean species.
    *
-   * @method faker.animal.cetacean
+   * @example
+   * faker.animal.cetacean() // 'Spinner Dolphin'
    */
   cetacean(): string {
     return this.faker.random.arrayElement(
@@ -65,6 +79,8 @@ export class Animal {
   /**
    * Returns a random horse breed.
    *
+   * @example
+   * faker.animal.horse() // 'Swedish Warmblood'
    */
   horse(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.horse);
@@ -73,6 +89,8 @@ export class Animal {
   /**
    * Returns a random bird species.
    *
+   * @example
+   * faker.animal.bird() // 'Buller's Shearwater'
    */
   bird(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.bird);
@@ -81,6 +99,8 @@ export class Animal {
   /**
    * Returns a random cow species.
    *
+   * @example
+   * faker.animal.cow() // 'Brava'
    */
   cow(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.cow);
@@ -89,6 +109,8 @@ export class Animal {
   /**
    * Returns a random fish species.
    *
+   * @example
+   * faker.animal.fish() // 'Mandarin fish'
    */
   fish(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.fish);
@@ -97,6 +119,8 @@ export class Animal {
   /**
    * Returns a random crocodilian species.
    *
+   * @example
+   * faker.animal.crocodilia() // 'Philippine Crocodile'
    */
   crocodilia(): string {
     return this.faker.random.arrayElement(
@@ -107,14 +131,18 @@ export class Animal {
   /**
    * Returns a random insect species.
    *
+   * @example
+   * faker.animal.insect() // 'Pyramid ant'
    */
   insect(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.insect);
   }
 
   /**
-   * Returns a random rabbit species
+   * Returns a random rabbit species.
    *
+   * @example
+   * faker.animal.rabbit() // 'Florida White'
    */
   rabbit(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.rabbit);
@@ -123,6 +151,8 @@ export class Animal {
   /**
    * Returns a random animal type.
    *
+   * @example
+   * faker.animal.type() // 'crocodilia'
    */
   type(): string {
     return this.faker.random.arrayElement(this.faker.definitions.animal.type);