faker 2.11.0 → 2.12.0

data/lib/faker/default/crypto_coin.rb

@@ -7,6 +7,15 @@ module Faker
       ACRONYM = 1
       URL_LOGO = 2
 
+      ##
+      # Produces a random crypto coin name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::CryptoCoin.coin_name #=> "Bitcoin"
+      #
+      # @faker.version 1.9.2
       def coin_name(legacy_coin = NOT_GIVEN, coin: coin_array)
         warn_for_deprecated_arguments do |keywords|
           keywords << :coin if legacy_coin != NOT_GIVEN
@@ -15,6 +24,15 @@ module Faker
         coin[COIN_NAME]
       end
 
+      ##
+      # Produces a random crypto coin acronym.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::CryptoCoin.acronym #=> "BTC"
+      #
+      # @faker.version 1.9.2
       def acronym(legacy_coin = NOT_GIVEN, coin: coin_array)
         warn_for_deprecated_arguments do |keywords|
           keywords << :coin if legacy_coin != NOT_GIVEN
@@ -23,6 +41,15 @@ module Faker
         coin[ACRONYM]
       end
 
+      ##
+      # Produces a random crypto coin logo url.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::CryptoCoin.url_logo #=> "https://i.imgur.com/EFz61Ei.png"
+      #
+      # @faker.version 1.9.2
       def url_logo(legacy_coin = NOT_GIVEN, coin: coin_array)
         warn_for_deprecated_arguments do |keywords|
           keywords << :coin if legacy_coin != NOT_GIVEN
@@ -31,10 +58,28 @@ module Faker
         coin[URL_LOGO]
       end
 
+      ##
+      # Produces a random crypto coin's name, acronym and logo in an array.
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::CryptoCoin.coin_array #=> ["Dash", "DASH", "https://i.imgur.com/2uX91cb.png"]
+      #
+      # @faker.version 1.9.2
       def coin_array
         fetch('crypto_coin.coin').split(',').map(&:strip)
       end
 
+      ##
+      # Produces a random crypto coin's name, acronym and logo in a hash.
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::CryptoCoin.coin_hash {:name=>"Ethereum", :acronym=>"ETH", :url_logo=>"https://i.imgur.com/uOPFCXj.png"}
+      #
+      # @faker.version 1.9.2
       def coin_hash
         coin = coin_array
 

data/lib/faker/default/driving_licence.rb

@@ -6,6 +6,23 @@ module Faker
     NI_CHANCE = 0.03 # NI Pop is about 3% of total UK population
 
     class << self
+      ##
+      # Produces a random British driving licence number.
+      #
+      # @param last_name [String] The last name of the driving licence's owner.
+      # @param initials [String] The initials of the driving licence's owner.
+      # @param gender [String] The gender of the driving licence's owner.
+      # @param date_of_birth [String] The date of birth of the driving licence's owner.
+      # @return [String]
+      #
+      # @example
+      #   Faker::DrivingLicence.british_driving_licence        #=> "MCDER712081VF7EK"
+      #   Faker::DrivingLicence.british_driving_licence(last_name: "O'Carroll",
+      #                                                 initials: "J",
+      #                                                 gender: :female,
+      #                                                 date_of_birth: Date.parse("1986-10-24")) #=> "OCARR815246J91HT"
+      #
+      # @faker.version 1.9.2
       # rubocop:disable Metrics/ParameterLists
       def british_driving_licence(legacy_last_name = NOT_GIVEN, legacy_initials = NOT_GIVEN, legacy_gender = NOT_GIVEN, legacy_date_of_birth = NOT_GIVEN, last_name: Faker::Name.last_name, initials: Faker::Name.initials, gender: random_gender, date_of_birth: Faker::Date.birthday(min_age: 18, max_age: 65))
         # rubocop:enable Metrics/ParameterLists
@@ -24,10 +41,35 @@ module Faker
         ].join
       end
 
+      ##
+      # Produces a random Northern Irish licence number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::DrivingLicence.northern_irish_driving_licence #=> "70702548"
+      #
+      # @faker.version 1.9.2
       def northern_irish_driving_licence
         Faker::Number.number(digits: 8).to_s
       end
 
+      ##
+      # Produces a random UK driving licence number in either GB or NI format, at a rate consistent with their relative populations
+      #
+      # @overload uk_driving_licence(last_name, initials, gender, date_of_birth)
+      #   @param last_name [String] The last name of the driving licence's owner.
+      #   @param initials [String] The initials of the driving licence's owner.
+      #   @param gender [String] The gender of the driving licence's owner.
+      #   @param date_of_birth [String] The date of birth of the driving licence's owner.
+      # @overload uk_driving_licence()
+      # @return [String]
+      #
+      # @example
+      #   Faker::DrivingLicence.uk_driving_licence             #=> "OCARR815246J91HT"
+      #   Faker::DrivingLicence.uk_driving_licence             #=> "70702548"
+      #
+      # @faker.version 1.9.2
       def uk_driving_licence(*args)
         if Faker::Config.random.rand < NI_CHANCE
           northern_irish_driving_licence

data/lib/faker/default/file.rb

@@ -3,6 +3,21 @@
 module Faker
   class File < Base
     class << self
+      ##
+      # Produces a random directory name.
+      #
+      # @param segment_count [Integer] Specifies the number of nested folders in the generated string.
+      # @param root [String] Specifies the root of the generated string.
+      # @param directory_separator [String] Specifies the separator between the segments.
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.dir #=> "et_error/sint_voluptas/quas_veritatis"
+      #   Faker::File.dir(segment_count: 2) #=> "ea-suscipit/ut-deleniti"
+      #   Faker::File.dir(segment_count: 3, root: nil, directory_separator: '/') #=> "est_porro/fugit_eveniet/incidunt-autem"
+      #   Faker::File.dir(segment_count: 3, root: nil, directory_separator: '\\') #=> "aut-ullam\\quia_quisquam\\ut-eos"
+      #
+      # @faker.version 1.6.4
       # rubocop:disable Metrics/ParameterLists
       def dir(legacy_segment_count = NOT_GIVEN, legacy_root = NOT_GIVEN, legacy_directory_separator = NOT_GIVEN, segment_count: 3, root: nil, directory_separator: ::File::Separator)
         # rubocop:enable Metrics/ParameterLists
@@ -20,14 +35,48 @@ module Faker
           .squeeze(directory_separator)
       end
 
+      ##
+      # Produces a random file extension.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.extension #=> "mp3"
+      #
+      # @faker.version 1.6.4
       def extension
         fetch('file.extension')
       end
 
+      ##
+      # Produces a random mime type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.mime_type #=> "application/pdf"
+      #
+      # @faker.version 1.6.4
       def mime_type
         fetch('file.mime_type')
       end
 
+      ##
+      # Produces a random file name.
+      #
+      # @param dir [String] Specifies the path used for the generated file.
+      # @param name [String] Specifies the filename used for the generated file.
+      # @param ext [String] Specifies the extension used the generated file.
+      # @param directory_separator [String] Specifies the separator between the directory and name elements.
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.file_name(dir: 'path/to') #=> "path/to/something_random.jpg"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz') #=> "foo/bar/baz.zip"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz', ext: 'doc') #=> "foo/bar/baz.doc"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz', ext: 'mp3', directory_separator: '\\') #=> "foo/bar\\baz.mp3"
+      #
+      # @faker.version 1.6.4
       # rubocop:disable Metrics/ParameterLists
       def file_name(legacy_dir = NOT_GIVEN, legacy_name = NOT_GIVEN, legacy_ext = NOT_GIVEN, legacy_directory_separator = NOT_GIVEN, dir: nil, name: nil, ext: nil, directory_separator: ::File::Separator)
         # rubocop:enable Metrics/ParameterLists

data/lib/faker/default/finance.rb

@@ -7,6 +7,18 @@ module Faker
                            maestro forbrugsforeningen laser].freeze
 
     class << self
+      ##
+      # Produces a random credit card number.
+      #
+      # @param types [String] Specific credit card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.credit_card #=> "3018-348979-1853"
+      #   Faker::Finance.credit_card(:mastercard) #=> "6771-8921-2291-6236"
+      #   Faker::Finance.credit_card(:mastercard, :visa) #=> "4448-8934-1277-7195"
+      #
+      # @faker.version 1.2.0
       def credit_card(*types)
         types = CREDIT_CARD_TYPES if types.empty?
         type = sample(types)
@@ -26,6 +38,18 @@ module Faker
         template.gsub('L', luhn_digit.to_s)
       end
 
+      ##
+      # Produces a random vat number.
+      #
+      # @param country [String] Two capital letter country code to use for the vat number.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.vat_number #=> "BR38.395.329/2471-83"
+      #   Faker::Finance.vat_number('DE') #=> "DE593306671"
+      #   Faker::Finance.vat_number('ZA') #=> "ZA79494416181"
+      #
+      # @faker.version 1.9.2
       def vat_number(legacy_country = NOT_GIVEN, country: 'BR')
         warn_for_deprecated_arguments do |keywords|
           keywords << :country if legacy_country != NOT_GIVEN

data/lib/faker/default/hipster.rb

@@ -3,11 +3,35 @@
 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
 
+      ##
+      # 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
       # rubocop:disable Metrics/ParameterLists
       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
@@ -30,6 +54,22 @@ module Faker
         words.each_with_index { |w, i| words[i] = word if w =~ /\s/ }
       end
 
+      ##
+      # 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 [Boolean] Specifies the number of random words to add
+      # @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.version 1.6.0
       # 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
@@ -42,6 +82,19 @@ module Faker
         words(number: word_count + rand(random_words_to_add.to_i).to_i, supplemental: supplemental, spaces_allowed: true).join(' ').capitalize + '.'
       end
 
+      ##
+      # 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
@@ -55,6 +108,22 @@ module Faker
         end
       end
 
+      ##
+      # 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
       # rubocop:disable Metrics/ParameterLists
       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
@@ -67,6 +136,19 @@ module Faker
         sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i, supplemental: supplemental).join(' ')
       end
 
+      ##
+      # 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 +162,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

data/lib/faker/default/invoice.rb

@@ -5,7 +5,18 @@ module Faker
     flexible :invoice
 
     class << self
-      # Generate random amount between values with 2 decimals
+      ##
+      # Produces a random amount between values with 2 decimals
+      #
+      # @param from [Integer] Specifies lower limit.
+      # @param to [Integer] Specifies upper limit.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Finance.amount_between #=> 0
+      #   Faker::Finance.amount_between(0, 10) #=> 4.33
+      #
+      # @faker.version 1.9.0
       def amount_between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 0, to: 0)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -15,8 +26,16 @@ module Faker
         Faker::Base.rand_in_range(from, to).round(2)
       end
 
-      # International bank slip reference https://en.wikipedia.org/wiki/Creditor_Reference
-      # ref is optional so that we can create unit tests
+      ##
+      # Produces a random valid reference accoring to the International bank slip reference https://en.wikipedia.org/wiki/Creditor_Reference
+      #
+      # @param ref [String] Specifies reference base.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Invoice.creditor_reference #=> "RF34118592570724925498"
+      #
+      # @faker.version 1.9.0
       def creditor_reference(legacy_ref = NOT_GIVEN, ref: '')
         warn_for_deprecated_arguments do |keywords|
           keywords << :ref if legacy_ref != NOT_GIVEN
@@ -27,8 +46,16 @@ module Faker
         'RF' + iban_checksum('RF', ref) + ref
       end
 
-      # Payment references have some rules in certain countries
-      # ref is optional so that we can create unit tests
+      ##
+      # Produces a random valid reference.
+      #
+      # @param ref [String] Specifies reference base.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Invoice.reference #=> "45656646957845"
+      #
+      # @faker.version 1.9.0
       def reference(legacy_ref = NOT_GIVEN, ref: '')
         warn_for_deprecated_arguments do |keywords|
           keywords << :ref if legacy_ref != NOT_GIVEN

data/lib/faker/default/json.rb

@@ -3,6 +3,23 @@ module Faker
     require 'json'
 
     class << self
+      ##
+      # Produces a random simple JSON formatted string.
+      #
+      # @param width [Integer] Specifies the number of key-value pairs.
+      # @param options [Hash] Specifies a Faker gem class to use for keys and for values, respectably. options_hash = {key: Class.method, value: Class.method}
+      # @return [Hash{String => String}]
+      #
+      # @example
+      #   Faker::Json.shallow_json(width: 3, options: { key: 'RockBand.name', value: 'Seinfeld.quote' }) # =>
+      #     {"Parliament Funkadelic":"They're real, and they're spectacular.",
+      #     "Fleetwood Mac":"I'm not a lesbian. I hate men, but I'm not a lesbian.",
+      #     "The Roots":"It became very clear to me sitting out there today that every decision
+      #     I've made in my entire life has been wrong. My life is the complete opposite of everything
+      #     I want it to be. Every instinct I have, in every aspect of life, be it something to wear,
+      #     something to eat - it's all been wrong."}
+      #
+      # @faker.version 1.9.2
       def shallow_json(legacy_width = NOT_GIVEN, legacy_options = NOT_GIVEN, width: 3, options: { key: 'Name.first_name', value: 'Name.first_name' })
         warn_for_deprecated_arguments do |keywords|
           keywords << :width if legacy_width != NOT_GIVEN
@@ -16,6 +33,44 @@ module Faker
         JSON.generate(hash)
       end
 
+      ##
+      # Produces a random nested JSON formatted string that can take JSON as an additional argument.
+      #
+      # @param json [Hash{String => String}] Specifies a Json.shallow_json and uses its keys as keys of the nested JSON.
+      # @param width [Integer] Specifies the number of nested key-value pairs.
+      # @param options [Hash] Specifies a Faker gem class to use for nested keys and for values, respectably. options_hash = {key: Class.method, value: Class.method}
+      # @return [Hash{String => String}]
+      #
+      # @example
+      #   json = Faker::Json.shallow_json(width: 3, options: { key: 'Name.first_name', value: 'Name.last_name' })
+      #   puts json # =>
+      #     {"Alisha":"Olson","Everardo":"DuBuque","Bridgette":"Turner"}
+      #
+      #   json2 = Faker::Json.add_depth_to_json(json: json, width: 2, options: { key: 'Name.first_name', value: 'Name.last_name' })
+      #   puts json2 # =>
+      #     {"Alisha":{"Daisy":"Trantow","Oda":"Haag"},
+      #      "Everardo":{"Javier":"Marvin","Eliseo":"Schuppe"},
+      #      "Bridgette":{"Jorge":"Kertzmann","Lelah":"MacGyver"}}
+      #
+      #    json3 = Faker::Json.add_depth_to_json(json: json2, width: 4, options: { key: 'Name.first_name', value: 'Name.last_name' })
+      #      puts json3 # =>
+      #        {"Alisha":
+      #          {"Daisy":
+      #            {"Bulah":"Wunsch","Cristian":"Champlin","Lester":"Bartoletti","Greg":"Jacobson"},
+      #           "Oda":
+      #             {"Salvatore":"Kuhlman","Aubree":"Okuneva","Larry":"Schmitt","Velva":"Gibson"}},
+      #         "Everardo":
+      #           {"Javier":
+      #             {"Eduardo":"Orn","Laila":"Kub","Thad":"Legros","Dion":"Wilderman"},
+      #           "Eliseo":
+      #             {"Olin":"Hilpert","Marisa":"Greenfelder","Karlee":"Schmitt","Judd":"Larkin"}},
+      #         "Bridgette":
+      #           {"Jorge":
+      #             {"Eloy":"Pfeffer","Kody":"Hansen","Paxton":"Lubowitz","Abe":"Lesch"},
+      #           "Lelah":
+      #             {"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