faker 2.15.1 → 2.16.0

data/lib/faker/default/json.rb

@@ -33,6 +33,8 @@ module Faker
         JSON.generate(hash)
       end
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random nested JSON formatted string that can take JSON as an additional argument.
       #
@@ -71,9 +73,7 @@ module Faker
       #             {"Rick":"Wiza","Bonita":"Bayer","Gardner":"Auer","Felicity":"Abbott"}}}
       #
       # @faker.version 1.9.2
-      # rubocop:disable Metrics/ParameterLists
       def add_depth_to_json(legacy_json = NOT_GIVEN, legacy_width = NOT_GIVEN, legacy_options = NOT_GIVEN, json: shallow_json, width: 3, options: { key: 'Name.first_name', value: 'Name.first_name' })
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :json if legacy_json != NOT_GIVEN
         end
@@ -93,6 +93,7 @@ module Faker
         end
         JSON.generate(hash)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 

data/lib/faker/default/lorem.rb

@@ -4,10 +4,32 @@ module Faker
   # Based on Perl's Text::Lorem
   class Lorem < Base
     class << self
+      ##
+      # Returs the random word
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.word   #=> "soluto"
+      #
+      # @faker.version 2.1.3
       def word
         sample(translate('faker.lorem.words'))
       end
 
+      ##
+      # Generates random 3 words
+      #
+      # @param number [Integer] Number of words to be generated
+      # @param supplemental [Boolean] Whether to attach supplemental words at the end, default is false
+      #
+      # @return [Array] Array for words
+      #
+      # @example
+      #   Faker::Lorem.words                                    #=> ["hic", "quia", "nihil"]
+      #   Faker::Lorem.words(number: 4)                         #=> ["est", "temporibus", "et", "quaerat"]
+      #   Faker::Lorem.words(number: 4, supplemental: true)    #=> ["nisi", "sit", "allatus", "consequatur"]
+      #
+      # @faker.version 2.1.3
       def words(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -23,6 +45,15 @@ module Faker
         shuffle(word_list)[0, resolved_num]
       end
 
+      ##
+      # Generates single character
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.character    #=> "e"
+      #
+      # @faker.version 2.1.3
       def character
         sample(Types::CHARACTERS)
       end
@@ -51,13 +82,42 @@ module Faker
         Alphanumeric.alphanumeric(number: number, min_alpha: min_alpha, min_numeric: min_numeric)
       end
 
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Generates the emoji
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.multibyte  #=> "😀"
+      #   Faker::Lorem.multibyte  #=> "❤"
+      #
+      # @faker.version 2.1.3
       def multibyte
         sample(translate('faker.lorem.multibyte')).pack('C*').force_encoding('utf-8')
       end
+      # rubocop:enable Style/AsciiComments
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Generates sentence
+      #
+      # @param word_count [Integer] How many words should be there in a sentence, default to 4
+      # @param supplemental [Boolean] Add supplemental words, default to false
+      # @param random_words_to_add [Integer] Add any random words, default to 0
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.sentence                                                             #=> "Magnam qui aut quidem."
+      #   Faker::Lorem.sentence(word_count: 5)                                              #=> "Voluptas rerum aut aliquam velit."
+      #   Faker::Lorem.sentence(word_count: 5, supplemental: true)                          #=> "Aut viscus curtus votum iusto."
+      #   Faker::Lorem.sentence(word_count: 5, supplemental: true, random_words_to_add:2)   #=> "Crinis quo cruentus velit animi vomer."
+      #
+      # @faker.version 2.1.3
       def sentence(legacy_word_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, supplemental: false, random_words_to_add: 0)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :word_count if legacy_word_count != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != NOT_GIVEN
@@ -66,7 +126,22 @@ module Faker
 
         words(number: word_count + rand(random_words_to_add.to_i), supplemental: supplemental).join(locale_space).capitalize + locale_period
       end
+      # rubocop:enable Metrics/ParameterLists
 
+      ##
+      # Generates three sentences
+      #
+      # @param number [Integer] How many sentences to be generated, default to 3
+      # @param supplemental [Boolean] Should add supplemental words, defaults to false
+      #
+      # @return [Array] Returns array for sentences.
+      #
+      # @example
+      #   Faker::Lorem.sentences                                  #=> ["Possimus non tenetur.", "Nulla non excepturi.", "Quisquam rerum facilis."]
+      #   Faker::Lorem.sentences(number: 2)                       #=> ["Nulla est natus.", "Perferendis autem cum."]
+      #   Faker::Lorem.sentences(number: 2, supplemental: true)   #=> ["Cito cena ad.", "Solvo animus allatus."]
+      #
+      # @faker.version 2.1.3
       def sentences(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -77,8 +152,28 @@ module Faker
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Generates three sentence paragraph
+      #
+      # @param sentence_count [Integer] Number of sentences in the paragraph
+      # @param supplemental [Boolean]
+      # @param random_sentences_to_add [Integer]
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.paragraph
+      #     #=> "Impedit et est. Aliquid deleniti necessitatibus. Et aspernatur minima."
+      #   Faker::Lorem.paragraph(sentence_count: 2)
+      #     #=> "Rerum fugit vitae. Et atque autem."
+      #   Faker::Lorem.paragraph(sentence_count: 2, supplemental: true)
+      #     #=> "Terreo coerceo utor. Vester sunt cogito."
+      #   Faker::Lorem.paragraph(sentence_count: 2, supplemental: true, random_sentences_to_add: 2)
+      #     #=> "Texo tantillus tamisium. Tribuo amissio tamisium. Facere aut canis."
+      #
+      # @faker.version 2.1.3
       def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_sentences_to_add = NOT_GIVEN, sentence_count: 3, supplemental: false, random_sentences_to_add: 0)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :sentence_count if legacy_sentence_count != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != NOT_GIVEN
@@ -87,7 +182,22 @@ module Faker
 
         sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i), supplemental: supplemental).join(locale_space)
       end
+      # rubocop:enable Metrics/ParameterLists
 
+      ##
+      # Generates three paragraphs
+      #
+      # @param number [Integer]
+      # @param supplemental [Boolean]
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Lorem.paragraphs
+      #   Faker::Lorem.paragraphs(number:2)
+      #   Faker::Lorem.paragraphs(number:2, supplemental: true)
+      #
+      # @faker.version 2.1.3
       def paragraphs(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -99,6 +209,20 @@ module Faker
         1.upto(resolve(number)).collect { paragraph(sentence_count: 3, supplemental: supplemental) }
       end
 
+      ##
+      # Generates paragraph with 256 characters
+      #
+      # @param number [Integer]
+      # @param supplemental [Boolean]
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.paragraph_by_chars
+      #   Faker::Lorem.paragraph_by_chars(number: 20)                       #=> "Sit modi alias. Imp."
+      #   Faker::Lorem.paragraph_by_chars(number: 20, supplemental: true)   #=> "Certus aveho admove."
+      #
+      # @faker.version 2.1.3
       def paragraph_by_chars(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 256, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -113,8 +237,24 @@ module Faker
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Returns the question with 4 words
+      #
+      # @param word_count [Integer]
+      # @param supplemental [Boolean]
+      # @param random_words_to_add [Integer]
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.question                                                               #=> "Natus deleniti sequi laudantium?"
+      #   Faker::Lorem.question(word_count: 2)                                                #=> "Quo ut?"
+      #   Faker::Lorem.question(word_count: 2, supplemental: true)                            #=> "Terga consequatur?"
+      #   Faker::Lorem.question(word_count: 2, supplemental: true, random_words_to_add: 2)    #=> "Depulso uter ut?"
+      #
+      # @faker.version 2.1.3
       def question(legacy_word_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, supplemental: false, random_words_to_add: 0)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :word_count if legacy_word_count != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != NOT_GIVEN
@@ -123,7 +263,22 @@ module Faker
 
         words(number: word_count + rand(random_words_to_add), supplemental: supplemental).join(' ').capitalize + locale_question_mark
       end
+      # rubocop:enable Metrics/ParameterLists
 
+      ##
+      # Generates array of three questions
+      #
+      # @param number [Integer]
+      # @param supplemental [Boolean]
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Lorem.questions                                  #=> ["Amet culpa enim?", "Voluptatem deleniti numquam?", "Veniam non cum?"]
+      #   Faker::Lorem.questions(number: 2)                       #=> ["Minus occaecati nobis?", "Veniam et alias?"]
+      #   Faker::Lorem.questions(number: 2, supplemental: true)   #=> ["Acceptus subito cetera?", "Aro sulum cubicularis?"]
+      #
+      # @faker.version 2.1.3
       def questions(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN

data/lib/faker/default/lorem_flickr.rb

@@ -5,6 +5,8 @@ module Faker
     class << self
       SUPPORTED_COLORIZATIONS = %w[red green blue].freeze
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random image URL from loremflickr.com.
       #
@@ -21,9 +23,7 @@ module Faker
       #   Faker::LoremFlickr.image(size: "50x60", search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/50/60/sports,fitness/all"
       #
       # @faker.version 1.9.0
-      # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: [], match_all: false)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :size if legacy_size != NOT_GIVEN
           keywords << :search_terms if legacy_search_terms != NOT_GIVEN
@@ -49,9 +49,7 @@ module Faker
       #   Faker::LoremFlickr.grayscale_image(size: "50x60", search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/g/50/60/sports,fitness/all"
       #
       # @faker.version 1.9.0
-      # rubocop:disable Metrics/ParameterLists
       def grayscale_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :size if legacy_size != NOT_GIVEN
           keywords << :search_terms if legacy_search_terms != NOT_GIVEN
@@ -79,9 +77,7 @@ module Faker
       #   Faker::LoremFlickr.pixelated_image(size: "50x60", search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/p/50/60/sports,fitness/all"
       #
       # @faker.version 1.9.0
-      # rubocop:disable Metrics/ParameterLists
       def pixelated_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :size if legacy_size != NOT_GIVEN
           keywords << :search_terms if legacy_search_terms != NOT_GIVEN
@@ -110,9 +106,7 @@ module Faker
       #   Faker::LoremFlickr.image(size: "50x60", color: 'blue', search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/blue/50/60/sports,fitness/all"
       #
       # @faker.version 1.9.0
-      # rubocop:disable Metrics/ParameterLists
       def colorized_image(legacy_size = NOT_GIVEN, legacy_color = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', color: 'red', search_terms: ['all'], match_all: false)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :size if legacy_size != NOT_GIVEN
           keywords << :color if legacy_color != NOT_GIVEN
@@ -125,6 +119,7 @@ module Faker
 
         build_url(size, color, search_terms, match_all)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 

data/lib/faker/default/lorem_pixel.rb

@@ -17,6 +17,8 @@ module Faker
                                 technics
                                 transport].freeze
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random image URL from lorempixel.com.
       #
@@ -39,7 +41,6 @@ module Faker
       #   Faker::LoremPixel.image(secure: false) #=> "http://lorempixel.com/300/300"
       #
       # @faker.version 1.7.0
-      # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_is_gray = NOT_GIVEN, legacy_category = NOT_GIVEN, legacy_number = NOT_GIVEN, legacy_text = NOT_GIVEN, legacy_secure = NOT_GIVEN, size: '300x300', is_gray: false, category: nil, number: nil, text: nil, secure: true)
         warn_for_deprecated_arguments do |keywords|
           keywords << :size if legacy_size != NOT_GIVEN

data/lib/faker/default/markdown.rb

@@ -117,9 +117,11 @@ module Faker
       end
 
       ##
-      # Produces a random method from the methods above or the methods listed in the arguments.
+      # Produces a random method from the methods above, excluding the methods listed in the arguments.
+      #
+      # @overload random(methods)
+      #   @param methods [Symbol] Specify which methods to exclude.
       #
-      # @param methods [Symbol] Specify which methods to use.
       # @return [String, Array<String>]
       #
       # @example

data/lib/faker/default/omniauth.rb

@@ -17,6 +17,8 @@ module Faker
     end
 
     class << self
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Generate a mock Omniauth response from Google.
       #
@@ -27,9 +29,7 @@ module Faker
       # @return [Hash] An auth hash in the format provided by omniauth-google.
       #
       # @faker.version 1.8.0
-      # rubocop:disable Metrics/ParameterLists
       def google(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 9).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -95,9 +95,7 @@ module Faker
       # @return [Hash] An auth hash in the format provided by omniauth-facebook.
       #
       # @faker.version 1.8.0
-      # rubocop:disable Metrics/ParameterLists
       def facebook(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_username = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, username: nil, uid: Number.number(digits: 7).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -156,9 +154,7 @@ module Faker
       # @return [Hash] An auth hash in the format provided by omniauth-twitter.
       #
       # @faker.version 1.8.0
-      # rubocop:disable Metrics/ParameterLists
       def twitter(legacy_name = NOT_GIVEN, legacy_nickname = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, nickname: nil, uid: Number.number(digits: 6).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :nickname if legacy_nickname != NOT_GIVEN
@@ -247,9 +243,7 @@ module Faker
       # @return [Hash] An auth hash in the format provided by omniauth-linkedin.
       #
       # @faker.version 1.8.0
-      # rubocop:disable Metrics/ParameterLists
       def linkedin(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 6).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -328,9 +322,7 @@ module Faker
       # @return [Hash] An auth hash in the format provided by omniauth-github.
       #
       # @faker.version 1.8.0
-      # rubocop:disable Metrics/ParameterLists
       def github(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 8).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -393,6 +385,7 @@ module Faker
           }
         }
       end
+      # rubocop:enable Metrics/ParameterLists
 
       ##
       # Generate a mock Omniauth response from Apple.

data/lib/faker/default/placeholdit.rb

@@ -5,6 +5,8 @@ module Faker
     class << self
       SUPPORTED_FORMATS = %w[png jpg gif jpeg].freeze
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random placeholder image from https://placehold.it.
       #
@@ -26,9 +28,7 @@ module Faker
       #   Faker::Placeholdit.image(size: '50x50', format: 'jpg', background_color: 'ffffff', text_color: '000', text: 'Some Custom Text') #=> "https://placehold.it/50x50.jpg/ffffff/000?text=Some Custom Text"
       #
       # @faker.version 1.6.0
-      # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_background_color = NOT_GIVEN, legacy_text_color = NOT_GIVEN, legacy_text = NOT_GIVEN, size: '300x300', format: 'png', background_color: nil, text_color: nil, text: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :size if legacy_size != NOT_GIVEN
           keywords << :format if legacy_format != NOT_GIVEN
@@ -51,6 +51,7 @@ module Faker
         image_url += "?text=#{text}" if text
         image_url
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 

data/lib/faker/default/string.rb

@@ -3,6 +3,8 @@
 module Faker
   class String < Base
     class << self
+      # rubocop:disable Style/AsciiComments
+
       ##
       # Produces a random UTF-8 string with optional nested length selectors.
       #
@@ -10,13 +12,11 @@ module Faker
       # @return [String]
       #
       # @example
-      #   rubocop:disable Style/AsciiComments
       #   Faker::String.random #=> "3 뇦\u0017&y\u{3A109}$8^4* 녹豿4좘툢ꔾ쉙6ɉ\uA6 8TN畀챵|\"3쇤Ŵ"
       #   Faker::String.random(length: 4) #=> "⼨%0*"
       #   Faker::String.random(length: 3..12) #=> "\u{69FDC};秨툫"
       #   Faker::String.random(length: [0, 6]) #=> "I轤𣴒P溟L"
       #   Faker::String.random(length: [1, (2..5), [3, 6], nil]) #=> "葓L#ћ"
-      #   rubocop:enable Style/AsciiComments
       #
       # @faker.version 1.9.0
       def random(legacy_length = NOT_GIVEN, length: 32)
@@ -26,6 +26,7 @@ module Faker
 
         utf8string select_a length
       end
+      # rubocop:enable Style/AsciiComments
 
       private