faker 2.11.0 → 2.17.0

data/lib/faker/default/hipster.rb

@@ -3,14 +3,38 @@
 module Faker
   class Hipster < Base
     class << self
+      ##
+      # Produces a random hipster word.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.word #=> "irony"
+      #
+      # @faker.version 1.6.0
       def word
         random_word = sample(translate('faker.hipster.words'))
         random_word =~ /\s/ ? word : random_word
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a random hipster word.
+      #
+      # @param number [Integer] Specifies the number of words returned
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @param spaces_allowed [Boolean] Specifies if the words may contain spaces
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Hipster.words #=> ["pug", "pitchfork", "chia"]
+      #   Faker::Hipster.words(number: 4) #=> ["ugh", "cardigan", "poutine", "stumptown"]
+      #   Faker::Hipster.words(number: 4, supplemental: true) #=> ["iste", "seitan", "normcore", "provident"]
+      #   Faker::Hipster.words(number: 4, supplemental: true, spaces_allowed: true) #=> ["qui", "magni", "craft beer", "est"]
+      #
+      # @faker.version 1.6.0
       def words(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number: 3, supplemental: false, spaces_allowed: false)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != NOT_GIVEN
@@ -30,18 +54,49 @@ module Faker
         words.each_with_index { |w, i| words[i] = word if w =~ /\s/ }
       end
 
-      # rubocop:disable Metrics/ParameterLists
-      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: 6)
-        # rubocop:enable Metrics/ParameterLists
+      ##
+      # Produces a random hipster sentence.
+      #
+      # @param word_count [Integer] Specifies the number of words in the sentence
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @param random_words_to_add [Integer] Specifies the number of random words to add
+      # @param open_compounds_allowed [Boolean] Specifies if the generated sentence can contain words having additional spaces
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.sentence #=> "Park iphone leggings put a bird on it."
+      #   Faker::Hipster.sentence(word_count: 3) #=> "Pour-over swag godard."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: true) #=> "Beard laboriosam sequi celiac."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: false, random_words_to_add: 4) #=> "Bitters retro mustache aesthetic biodiesel 8-bit."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: true, random_words_to_add: 4) #=> "Occaecati deleniti messenger bag meh crucifix autem."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: true, random_words_to_add: 0, open_compounds_allowed: true) #=> "Kale chips nihil eos."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: true, random_words_to_add: 0, open_compounds_allowed: false) #=> "Dreamcatcher umami fixie."
+      #
+      # @faker.version 1.6.0
+      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: 6, open_compounds_allowed: true)
         warn_for_deprecated_arguments do |keywords|
           keywords << :word_count if legacy_word_count != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != 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, supplemental: supplemental, spaces_allowed: true).join(' ').capitalize + '.'
+        "#{words(number: word_count + rand(random_words_to_add.to_i).to_i, supplemental: supplemental, spaces_allowed: open_compounds_allowed).join(' ').capitalize}."
       end
-
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # Produces random hipster sentences.
+      #
+      # @param number [Integer] Specifies the number of sentences returned
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Hipster.sentences #=> ["Godard pitchfork vinegar chillwave everyday 90's whatever.", "Pour-over artisan distillery street waistcoat.", "Salvia yr leggings franzen blue bottle."]
+      #   Faker::Hipster.sentences(number: 1) #=> ["Before they sold out pinterest venmo umami try-hard ugh hoodie artisan."]
+      #   Faker::Hipster.sentences(number: 1, supplemental: true) #=> ["Et sustainable optio aesthetic et."]
+      #
+      # @faker.version 1.6.0
       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
@@ -56,8 +111,24 @@ module Faker
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a random hipster paragraph.
+      #
+      # @param sentence_count [Integer] Specifies the number of sentences in the paragraph
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @param random_sentences_to_add [Boolean] Specifies the number of random sentences to add
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.paragraph #=> "Migas fingerstache pbr&b tofu. Polaroid distillery typewriter echo tofu actually. Slow-carb fanny pack pickled direct trade scenester mlkshk plaid. Banjo venmo chambray cold-pressed typewriter. Fap skateboard intelligentsia."
+      #   Faker::Hipster.paragraph(sentence_count: 2) #=> "Yolo tilde farm-to-table hashtag. Lomo kitsch disrupt forage +1."
+      #   Faker::Hipster.paragraph(sentence_count: 2, supplemental: true) #=> "Typewriter iste ut viral kombucha voluptatem. Sint voluptates saepe. Direct trade irony chia excepturi yuccie. Biodiesel esse listicle et quam suscipit."
+      #   Faker::Hipster.paragraph(sentence_count: 2, supplemental: false, random_sentences_to_add: 4) #=> "Selvage vhs chartreuse narwhal vinegar. Authentic vinyl truffaut carry vhs pop-up. Hammock everyday iphone locavore thundercats bitters vegan goth. Fashion axe banh mi shoreditch whatever artisan."
+      #   Faker::Hipster.paragraph(sentence_count: 2, supplemental: true, random_sentences_to_add: 4) #=> "Deep v gluten-free unde waistcoat aperiam migas voluptas dolorum. Aut drinking illo sustainable sapiente. Direct trade fanny pack kale chips ennui semiotics."
+      #
+      # @faker.version 1.6.0
       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: 3)
-        # 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
@@ -66,7 +137,21 @@ module Faker
 
         sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i, supplemental: supplemental).join(' ')
       end
-
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # Produces random hipster paragraphs.
+      #
+      # @param number [Integer] Specifies the number of paragraphs
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Hipster.paragraphs #=> ["Tilde microdosing blog cliche meggings. Intelligentsia five dollar toast forage yuccie. Master kitsch knausgaard. Try-hard everyday trust fund mumblecore.", "Normcore viral pickled. Listicle humblebrag swag tote bag. Taxidermy street hammock neutra butcher cred kale chips. Blog portland humblebrag trust fund irony.", "Single-origin coffee fixie cleanse tofu xoxo. Post-ironic tote bag ramps gluten-free locavore mumblecore hammock. Umami loko twee. Ugh kitsch before they sold out."]
+      #   Faker::Hipster.paragraphs(number: 1) #=> ["Skateboard cronut synth +1 fashion axe. Pop-up polaroid skateboard asymmetrical. Ennui fingerstache shoreditch before they sold out. Tattooed pitchfork ramps. Photo booth yr messenger bag raw denim bespoke locavore lomo synth."]
+      #   Faker::Hipster.paragraphs(number: 1, supplemental: true) #=> ["Quae direct trade pbr&b quo taxidermy autem loko. Umami quas ratione migas cardigan sriracha minima. Tenetur perspiciatis pickled sed eum doloribus truffaut. Excepturi dreamcatcher meditation."]
+      #
+      # @faker.version 1.6.0
       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
@@ -80,6 +165,18 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random hipster paragraph by characters.
+      #
+      # @param characters [Integer] Specifies the number of characters in the paragraph
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.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."
+      #   Faker::Hipster.paragraph_by_chars(characters: 256, supplemental: false) #=> "Hella kogi blog narwhal sartorial selfies mustache schlitz. Bespoke normcore kitsch cred hella fixie. Park aesthetic fixie migas twee. Cliche mustache brunch tumblr fixie godard. Drinking pop-up synth hoodie dreamcatcher typewriter. Kitsch biodiesel green."
+      #
+      # @faker.version 1.6.0
       def paragraph_by_chars(legacy_characters = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, characters: 256, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :characters if legacy_characters != NOT_GIVEN
@@ -88,9 +185,9 @@ module Faker
 
         paragraph = paragraph(sentence_count: 3, supplemental: supplemental)
 
-        paragraph += ' ' + paragraph(sentence_count: 3, supplemental: supplemental) while paragraph.length < characters
+        paragraph += " #{paragraph(sentence_count: 3, supplemental: supplemental)}" while paragraph.length < characters
 
-        paragraph[0...characters - 1] + '.'
+        "#{paragraph[0...characters - 1]}."
       end
     end
   end

data/lib/faker/default/id_number.rb

@@ -19,10 +19,28 @@ module Faker
     CHILEAN_MODULO = 11
 
     class << self
+      ##
+      # Produces a random valid US Social Security number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.valid #=> "552-56-3593"
+      #
+      # @faker.version 1.6.0
       def valid
         _translate('valid')
       end
 
+      ##
+      # Produces a random invalid US Social Security number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.invalid #=> "311-72-0000"
+      #
+      # @faker.version 1.6.0
       def invalid
         _translate('invalid')
       end
@@ -33,6 +51,15 @@ module Faker
         INVALID_SSN.any? { |regex| regex =~ ssn } ? ssn_valid : ssn
       end
 
+      ##
+      # Produces a random Spanish citizen identifier (DNI).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.spanish_citizen_number #=> "53290236-H"
+      #
+      # @faker.version 1.9.0
       def spanish_citizen_number
         num = Faker::Number.number(digits: 8)
         mod = num.to_i % 23
@@ -40,6 +67,15 @@ module Faker
         "#{num}-#{check}"
       end
 
+      ##
+      # Produces a random Spanish foreign born citizen identifier (NIE).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.spanish_foreign_citizen_number #=> "Z-1600870-Y"
+      #
+      # @faker.version 1.9.0
       def spanish_foreign_citizen_number
         code = 'XYZ'
         digits = Faker::Number.number(digits: 7)
@@ -50,6 +86,16 @@ module Faker
         "#{prefix}-#{digits}-#{check}"
       end
 
+      ##
+      # Produces a random valid South African ID Number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.south_african_id_number #=> "8105128870184"
+      #   Faker::IDNumber.valid_south_african_id_number #=> "8105128870184"
+      #
+      # @faker.version 1.9.2
       def valid_south_african_id_number
         id_number = [
           Faker::Date.birthday.strftime('%y%m%d'),
@@ -63,6 +109,15 @@ module Faker
 
       alias south_african_id_number valid_south_african_id_number
 
+      ##
+      # Produces a random invalid South African ID Number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.invalid_south_african_id_number #=> "1642972065088"
+      #
+      # @faker.version 1.9.2
       def invalid_south_african_id_number
         invalid_date_of_birth = [
           Faker::Number.number(digits: 2),
@@ -80,6 +135,17 @@ module Faker
         [id_number, south_african_id_checksum_digit(id_number)].join
       end
 
+      ##
+      # Produces a random Brazilian Citizen Number (CPF).
+      #
+      # @param formatted [Boolean] Specifies if the number is formatted with dividers.
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.brazilian_citizen_number #=> "53540542221"
+      #   Faker::IDNumber.brazilian_citizen_number(formatted: true) #=> "535.405.422-21"
+      #
+      # @faker.version 1.9.2
       def brazilian_citizen_number(legacy_formatted = NOT_GIVEN, formatted: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :formatted if legacy_formatted != NOT_GIVEN
@@ -94,6 +160,17 @@ module Faker
 
       alias brazilian_cpf brazilian_citizen_number
 
+      ##
+      # Produces a random Brazilian ID Number (RG).
+      #
+      # @param formatted [Boolean] Specifies if the number is formatted with dividers.
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.brazilian_id #=> "493054029"
+      #   Faker::IDNumber.brazilian_id(formatted: true) #=> "49.305.402-9"
+      #
+      # @faker.version 2.1.2
       def brazilian_id(legacy_formatted = NOT_GIVEN, formatted: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :formatted if legacy_formatted != NOT_GIVEN
@@ -107,11 +184,20 @@ module Faker
 
       alias brazilian_rg brazilian_id
 
+      ##
+      # Produces a random Chilean ID (Rut with 8 digits).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.chilean_id #=> "15620613-K"
+      #
+      # @faker.version 2.1.2
       def chilean_id
         digits = Faker::Number.number(digits: 8)
         verification_code = chilean_verification_code(digits)
 
-        digits.to_s + '-' + verification_code.to_s
+        "#{digits}-#{verification_code}"
       end
 
       private
@@ -170,7 +256,7 @@ module Faker
         end * 10
       end
 
-      def brazilian_document_digit(checksum, id = false)
+      def brazilian_document_digit(checksum, id: false)
         remainder = checksum % 11
         id ? brazilian_id_digit(remainder) : brazilian_citizen_number_digit(remainder)
       end