faker 1.9.6 → 2.7.0

data/lib/faker/books/lovecraft.rb

@@ -4,33 +4,143 @@ module Faker
   class Books
     class Lovecraft < Base
       class << self
+        ##
+        # Produces the name of a location
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.location #=> "Kingsport"
+        #
+        # @faker.version 1.9.3
         def location
           fetch('lovecraft.location')
         end
 
-        def fhtagn(number_of = 1)
-          Array.new(number_of) { fetch('lovecraft.fhtagn') }.join('. ')
+        ##
+        # @param number [Integer] The number of times to repeat the chant
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.fhtagn
+        #     #=> "Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn"
+        # @example
+        #   Faker::Books::Lovecraft.fhtagn(number: 3)
+        #     #=> "Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fht...
+        #
+        # @faker.version 1.9.3
+        def fhtagn(legacy_number = NOT_GIVEN, number: 1)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
+          end
+
+          Array.new(number) { fetch('lovecraft.fhtagn') }.join('. ')
         end
 
+        ##
+        # Produces the name of a deity
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.deity #=> "Shub-Niggurath"
+        #
+        # @faker.version 1.9.3
         def deity
           fetch('lovecraft.deity')
         end
 
+        ##
+        # Produces the name of a tome
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.tome #=> "Book of Eibon"
+        #
+        # @faker.version 1.9.3
         def tome
           fetch('lovecraft.tome')
         end
 
-        def sentence(word_count = 4, random_words_to_add = 6)
-          words(word_count + rand(random_words_to_add.to_i).to_i, true).join(' ').capitalize + '.'
+        ##
+        # Produces a random sentence
+        #
+        # @param word_count [Integer] The number of words to have in the sentence
+        # @param random_words_to_add [Integer]
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.sentence
+        #     #=> "Furtive antiquarian squamous dank cat loathsome amorphous lurk."
+        # @example
+        #   Faker::Books::Lovecraft.sentence(word_count: 3)
+        #     #=> "Daemoniac antediluvian fainted squamous comprehension gambrel nameless singular."
+        # @example
+        #   Faker::Books::Lovecraft.sentence(word_count: 3, random_words_to_add: 1)
+        #     #=> "Amorphous indescribable tenebrous."
+        #
+        # @faker.version 1.9.3
+        def sentence(legacy_word_count = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, random_words_to_add: 6)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :word_count if legacy_word_count != NOT_GIVEN
+            keywords << :random_words_to_add if legacy_random_words_to_add != NOT_GIVEN
+          end
+
+          words(number: word_count + rand(random_words_to_add.to_i).to_i, spaces_allowed: true).join(' ').capitalize + '.'
         end
 
+        ##
+        # Produces a random word
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.word #=> "furtive"
+        #
+        # @faker.version 1.9.3
         def word
           random_word = sample(translate('faker.lovecraft.words'))
           random_word =~ /\s/ ? word : random_word
         end
 
-        def words(num = 3, spaces_allowed = false)
-          resolved_num = resolve(num)
+        ##
+        # Produces a array of random words
+        #
+        # @param number [Integer] Number of words to generate
+        # @param spaces_allowed [Boolean] If true, generated words can contain spaces
+        #
+        # @return [Array<String>]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.words
+        #   #=> [
+        #   #     "manuscript",
+        #   #     "abnormal",
+        #   #     "singular",
+        #   #   ]
+        # @example
+        #   Faker::Books::Lovecraft.words(number: 2)
+        #   #=> [
+        #   #     "daemoniac",
+        #   #     "cat",
+        #   #   ]
+        # @example
+        #   Faker::Books::Lovecraft.words(number: 2, spaces_allowed: 1)
+        #   #=> [
+        #   #     "lurk",
+        #   #     "charnel",
+        #   #   ]
+        #
+        # @faker.version 1.9.3
+        def words(legacy_number = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number: 3, spaces_allowed: false)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
+            keywords << :spaces_allowed if legacy_spaces_allowed != NOT_GIVEN
+          end
+
+          resolved_num = resolve(number)
           word_list = translate('faker.lovecraft.words')
           word_list *= ((resolved_num / word_list.length) + 1)
 
@@ -40,32 +150,125 @@ module Faker
           words.each_with_index { |w, i| words[i] = word if w =~ /\s/ }
         end
 
-        def sentences(sentence_count = 3)
+        ##
+        # Produces a array of random sentences
+        #
+        # @param number [Integer] Number of sentences to generate
+        #
+        # @return [Array<String>]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.sentences
+        #   #=> [
+        #   #     "Nameless loathsome decadent gambrel.",
+        #   #     "Ululate swarthy immemorial cat madness gibbous unmentionable unnamable.",
+        #   #     "Decadent antediluvian non-euclidean tentacles amorphous tenebrous.",
+        #   #   ]
+        # @example
+        #   Faker::Books::Lovecraft.sentences(number: 2)
+        #   #=> [
+        #   #     "Antediluvian amorphous unmentionable singular accursed squamous immemorial.",
+        #   #     "Gambrel daemoniac gibbous stygian shunned ululate iridescence abnormal.",
+        #   #   ]
+        #
+        # @faker.version 1.9.3
+        def sentences(legacy_number = NOT_GIVEN, number: 3)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
+          end
+
           [].tap do |sentences|
-            1.upto(resolve(sentence_count)) do
-              sentences << sentence(3)
+            1.upto(resolve(number)) do
+              sentences << sentence(word_count: 3)
             end
           end
         end
 
-        def paragraph(sentence_count = 3, random_sentences_to_add = 3)
-          sentences(resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i).join(' ')
+        ##
+        # Produces a random paragraph
+        #
+        # @param sentence_count [Integer] Number of sentences to generate
+        # @param random_sentences_to_add [Integer]
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.paragraph
+        #     #=> "Squamous nameless daemoniac fungus ululate. Cyclopean stygian decadent loathsome manuscript tenebrous. Foetid abnormal stench. Dank non-euclidean comprehension eldritch. Charnel singular shunned lurk effulgence fungus."
+        # @example
+        #   Faker::Books::Lovecraft.paragraph(sentence_count: 2)
+        #     #=> "Decadent lurk tenebrous loathsome furtive spectral amorphous gibbous. Gambrel eldritch daemoniac cat madness comprehension stygian effulgence."
+        # @example
+        #   Faker::Books::Lovecraft.paragraph(sentence_count: 1, random_sentences_to_add: 1)
+        #     #=> "Stench cyclopean fainted antiquarian nameless. Antiquarian ululate tenebrous non-euclidean effulgence."
+        #
+        # @faker.version 1.9.3
+        def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_random_sentences_to_add = NOT_GIVEN, sentence_count: 3, random_sentences_to_add: 3)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :sentence_count if legacy_sentence_count != NOT_GIVEN
+            keywords << :random_sentences_to_add if legacy_random_sentences_to_add != NOT_GIVEN
+          end
+
+          sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i).join(' ')
         end
 
-        def paragraphs(paragraph_count = 3)
+        ##
+        # Produces a array of random paragraphs
+        #
+        # @param number [Integer] Number of paragraphs to generate
+        #
+        # @return [Array<String>]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.paragraphs
+        #   #=> [
+        #   #     "Noisome daemoniac gibbous abnormal antediluvian. Unutterable fung...
+        #   #     "Non-euclidean immemorial indescribable accursed furtive. Dank unn...
+        #   #     "Charnel antediluvian unnamable cat blasphemous comprehension tene...
+        #   #   ]
+        # @example
+        #   Faker::Books::Lovecraft.paragraphs(number: 2)
+        #   #=> [
+        #   #     "Hideous amorphous manuscript antediluvian non-euclidean cat eldri...
+        #   #     "Tenebrous unnamable comprehension antediluvian lurk. Lurk spectra...
+        #   #   ]
+        #
+        # @faker.version 1.9.3
+        def paragraphs(legacy_number = NOT_GIVEN, number: 3)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
+          end
+
           [].tap do |paragraphs|
-            1.upto(resolve(paragraph_count)) do
-              paragraphs << paragraph(3)
+            1.upto(resolve(number)) do
+              paragraphs << paragraph(sentence_count: 3)
             end
           end
         end
 
-        def paragraph_by_chars(chars = 256)
-          paragraph = paragraph(3)
+        ##
+        # @param characters [Integer] Number of characters to generate in the paragraph
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Books::Lovecraft.paragraph_by_chars
+        #     #=> "Truffaut stumptown trust fund 8-bit messenger bag portland. Meh kombucha selvage swag biodiesel. Lomo kinfolk jean shorts asymmetrical diy. Wayfarers portland twee stumptown. Wes anderson biodiesel retro 90's pabst. Diy echo 90's mixtape semiotics. Cornho."
+        # @example
+        #   Faker::Books::Lovecraft.paragraph_by_chars(characters: 128)
+        #     #=> "Effulgence madness noisome. Fungus stygian mortal madness amorphous dank. Decadent noisome hideous effulgence. Tentacles charne."
+        #
+        # @faker.version 1.9.3
+        def paragraph_by_chars(legacy_characters = NOT_GIVEN, characters: 256)
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :characters if legacy_characters != NOT_GIVEN
+          end
+
+          paragraph = paragraph(sentence_count: 3)
 
-          paragraph += ' ' + paragraph(3) while paragraph.length < chars
+          paragraph += ' ' + paragraph(sentence_count: 3) while paragraph.length < characters
 
-          paragraph[0...chars - 1] + '.'
+          paragraph[0...characters - 1] + '.'
         end
       end
     end

data/lib/faker/creature/animal.rb

@@ -1,9 +1,18 @@
 # frozen_string_literal: true
 
 module Faker
-  module Creature
+  class Creature
     class Animal < Base
       class << self
+        ##
+        # Produces a random animal name
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Animal.name #=> "fly"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.animal.name')
         end

data/lib/faker/creature/cat.rb

@@ -1,19 +1,46 @@
 # frozen_string_literal: true
 
 module Faker
-  module Creature
+  class Creature
     class Cat < Base
       flexible :cat
 
       class << self
+        ##
+        # Produces a random name for a cat
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Cat.name #=> "Felix"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.cat.name')
         end
 
+        ##
+        # Produces a random cat breed
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Cat.breed #=> "Scottish Fold"
+        #
+        # @faker.version 1.9.2
         def breed
           fetch('creature.cat.breed')
         end
 
+        ##
+        # Produces a random cat breed registry
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Cat.registry #=> "Fancy Southern Africa Cat Council"
+        #
+        # @faker.version 1.9.2
         def registry
           fetch('creature.cat.registry')
         end

data/lib/faker/creature/dog.rb

@@ -1,39 +1,111 @@
 # frozen_string_literal: true
 
 module Faker
-  module Creature
+  class Creature
     class Dog < Base
       flexible :dog
 
       class << self
+        ##
+        # Produces a random name for a dog
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.name #=> "Spike"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.dog.name')
         end
 
+        ##
+        # Produces a random dog breed
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.breed #=> "Yorkshire Terrier"
+        #
+        # @faker.version 1.9.2
         def breed
           fetch('creature.dog.breed')
         end
 
+        ##
+        # Produces a random sound made by a dog
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.sound #=> "woof woof"
+        #
+        # @faker.version 1.9.2
         def sound
           fetch('creature.dog.sound')
         end
 
+        ##
+        # Produces a random dog meme phrase
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.meme_phrase #=> "smol pupperino"
+        #
+        # @faker.version 1.9.2
         def meme_phrase
           fetch('creature.dog.meme_phrase')
         end
 
+        ##
+        # Produces a random dog age
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.age #=> "puppy"
+        #
+        # @faker.version 1.9.2
         def age
           fetch('creature.dog.age')
         end
 
+        ##
+        # Produces a random gender
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.gender #=> "Female"
+        #
+        # @faker.version 1.9.2
         def gender
           Faker::Gender.binary_type
         end
 
+        ##
+        # Produces a random coat length
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.coat_length #=> "short"
+        #
+        # @faker.version 1.9.2
         def coat_length
           fetch('creature.dog.coat_length')
         end
 
+        ##
+        # Produces a random size of a dog
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.size #=> "small"
+        #
+        # @faker.version 1.9.2
         def size
           fetch('creature.dog.size')
         end