faker 2.12.0 → 2.16.0

data/lib/faker/default/faker_adjective.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Faker
+  class Adjective < Base
+    flexible :adjective
+
+    class << self
+      ##
+      # Produces a positive adjective.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Adjective.positive #=> "Kind"
+      #
+      # @faker.version next
+      def positive
+        fetch('adjective.positive')
+      end
+
+      ##
+      # Produces a negative adjective.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Adjective.negative #=> "Creepy"
+      #
+      # @faker.version next
+      def negative
+        fetch('adjective.negative')
+      end
+    end
+  end
+end

data/lib/faker/default/file.rb

@@ -3,6 +3,8 @@
 module Faker
   class File < Base
     class << self
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random directory name.
       #
@@ -18,9 +20,7 @@ module Faker
       #   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
         warn_for_deprecated_arguments do |keywords|
           keywords << :segment_count if legacy_segment_count != NOT_GIVEN
           keywords << :root if legacy_root != NOT_GIVEN
@@ -34,6 +34,7 @@ module Faker
           .join(directory_separator)
           .squeeze(directory_separator)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       ##
       # Produces a random file extension.
@@ -61,6 +62,8 @@ module Faker
         fetch('file.mime_type')
       end
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random file name.
       #
@@ -77,9 +80,7 @@ module Faker
       #   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
         warn_for_deprecated_arguments do |keywords|
           keywords << :dir if legacy_dir != NOT_GIVEN
           keywords << :name if legacy_name != NOT_GIVEN
@@ -93,6 +94,7 @@ module Faker
 
         [dir, name].join(directory_separator) + ".#{ext}"
       end
+      # rubocop:enable Metrics/ParameterLists
     end
   end
 end

data/lib/faker/default/finance.rb

@@ -6,6 +6,8 @@ module Faker
                            diners_club jcb switch solo dankort
                            maestro forbrugsforeningen laser].freeze
 
+    MARKET_LIST = %i[nyse nasdaq].freeze
+
     class << self
       ##
       # Produces a random credit card number.
@@ -63,6 +65,25 @@ module Faker
       def vat_number_keys
         translate('faker.finance.vat_number').keys
       end
+
+      ##
+      # Returns a randomly-selected stock ticker from a specified market.
+      #
+      # @param markets [String] The name of the market to choose the ticker from (e.g. NYSE, NASDAQ)
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.ticker #=> 'AMZN'
+      #   Faker::Finance.vat_number('NASDAQ') #=> 'GOOG'
+      #
+      # @faker.version next
+      def ticker(*markets)
+        markets = MARKET_LIST if markets.empty?
+        market = sample(markets)
+        fetch("finance.ticker.#{market}")
+      rescue I18n::MissingTranslationData
+        raise ArgumentError, "Could not find market named #{market}"
+      end
     end
   end
 end

data/lib/faker/default/food.rb

@@ -93,7 +93,7 @@ module Faker
       #
       # @faker.version 1.7.0
       def measurement
-        fetch('food.measurement_sizes') + ' ' + fetch('food.measurements')
+        "#{fetch('food.measurement_sizes')} #{fetch('food.measurements')}"
       end
 
       ##

data/lib/faker/default/gender.rb

@@ -37,7 +37,7 @@ module Faker
       # @example
       #   Faker::Gender.short_binary_type #=> "f"
       #
-      # @faker.version next
+      # @faker.version 2.13.0
       def short_binary_type
         fetch('gender.short_binary_types')
       end

data/lib/faker/default/hipster.rb

@@ -17,6 +17,8 @@ module Faker
         random_word =~ /\s/ ? word : random_word
       end
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random hipster word.
       #
@@ -32,9 +34,7 @@ module Faker
       #   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
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != NOT_GIVEN
@@ -59,7 +59,8 @@ module Faker
       #
       # @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
+      # @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
@@ -68,19 +69,20 @@ module Faker
       #   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
-      # 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
+      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.
@@ -108,6 +110,8 @@ module Faker
         end
       end
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a random hipster paragraph.
       #
@@ -124,9 +128,7 @@ module Faker
       #   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
         warn_for_deprecated_arguments do |keywords|
           keywords << :sentence_count if legacy_sentence_count != NOT_GIVEN
           keywords << :supplemental if legacy_supplemental != NOT_GIVEN
@@ -135,6 +137,7 @@ 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.
@@ -182,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

data/lib/faker/default/internet.rb

@@ -3,35 +3,91 @@
 module Faker
   class Internet < Base
     class << self
+      ##
+      # Returns the email address
+      #
+      # @return [String]
+      #
+      # @param name [String]
+      # @param separators [Array]
+      # @param domain [String]
+      #
+      # @example
+      #   Faker::Internet.email                                                           #=> "samsmith@faker.com"
+      #   Faker::Internet.email(name: 'smith')                                            #=> "smith@faker.com"
+      #   Faker::Internet.email(name: 'sam smith', separators: ['-'])                     #=> "sam-smith@faker.com"
+      #   Faker::Internet.email(name: 'sam smith', separators: ['-'], domain: 'gmail')    #=> "sam-smith@gmail.com"
       def email(legacy_name = NOT_GIVEN, legacy_separators = NOT_GIVEN, name: nil, separators: nil, domain: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :separators if legacy_separators != NOT_GIVEN
         end
 
-        if separators
-          [username(specifier: name, separators: separators), domain_name(domain: domain)].join('@')
-        else
-          [username(specifier: name), domain_name(domain: domain)].join('@')
-        end
+        local_part = if separators
+                       username(specifier: name, separators: separators)
+                     else
+                       username(specifier: name)
+                     end
+
+        sanitized_local_part = sanitize_email_local_part(local_part)
+        construct_email(sanitized_local_part, domain_name(domain: domain))
       end
 
+      ##
+      # Returns the email address with doamin either gmail.com, yahoo.com or hotmail.com
+      #
+      # @return [String]
+      #
+      # @param name [String]
+      #
+      # @example
+      #   Faker::Internet.free_email                                                           #=> "samsmith@gmail.com"
+      #   Faker::Internet.free_email(name: 'smith')                                            #=> "smith@yahoo.com"
       def free_email(legacy_name = NOT_GIVEN, name: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
         end
 
-        [username(specifier: name), fetch('internet.free_email')].join('@')
+        construct_email(
+          sanitize_email_local_part(username(specifier: name)),
+          fetch('internet.free_email')
+        )
       end
 
+      ##
+      # Returns the email address with fixed domain name as 'example'
+      #
+      # @return [String]
+      #
+      # @param name [String]
+      #
+      # @example
+      #   Faker::Internet.safe_email                                                           #=> "samsmith@example.com"
+      #   Faker::Internet.safe_email(name: 'smith')                                            #=> "smith@example.net"
       def safe_email(legacy_name = NOT_GIVEN, name: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
         end
 
-        [username(specifier: name), 'example.' + sample(%w[org com net])].join('@')
+        construct_email(
+          sanitize_email_local_part(username(specifier: name)),
+          "example.#{sample(%w[org com net])}"
+        )
       end
 
+      ##
+      # Returns the username
+      #
+      # @return [String]
+      #
+      # @param specifier [Integer, Range] When int value passed it returns the username longer than specifier. Max value can be 10^6
+      # @param separator [Array]
+      #
+      # @wxample
+      #   Faker::Internet.username(specifier: 10)                     #=> "lulu.goodwin"
+      #   Faker::Internet.username(specifier: 5..10)                  #=> "morris"
+      #   Faker::Internet.username(specifier: 5..10)                  #=> "berryberry"
+      #   Faker::Internet.username(specifier: 20, separators: ['-'])  #=> "nikki_sawaynnikki_saway"
       def username(legacy_specifier = NOT_GIVEN, legacy_separators = NOT_GIVEN, specifier: nil, separators: %w[. _])
         warn_for_deprecated_arguments do |keywords|
           keywords << :specifier if legacy_specifier != NOT_GIVEN
@@ -41,7 +97,8 @@ module Faker
         with_locale(:en) do
           return shuffle(specifier.scan(/[[:word:]]+/)).join(sample(separators)).downcase if specifier.respond_to?(:scan)
 
-          if specifier.is_a?(Integer)
+          case specifier
+          when Integer
             # If specifier is Integer and has large value, Argument error exception is raised to overcome memory full error
             raise ArgumentError, 'Given argument is too large' if specifier > 10**6
 
@@ -53,7 +110,7 @@ module Faker
               break unless result.length < specifier && tries < 7
             end
             return result * (specifier / result.length + 1) if specifier.positive?
-          elsif specifier.is_a?(Range)
+          when Range
             tries = 0
             result = nil
             loop do
@@ -98,7 +155,6 @@ module Faker
       #
       # @faker.version 2.1.3
       def password(legacy_min_length = NOT_GIVEN, legacy_max_length = NOT_GIVEN, legacy_mix_case = NOT_GIVEN, legacy_special_characters = NOT_GIVEN, min_length: 8, max_length: 16, mix_case: true, special_characters: false)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_length if legacy_min_length != NOT_GIVEN
           keywords << :max_length if legacy_max_length != NOT_GIVEN
@@ -106,7 +162,7 @@ module Faker
           keywords << :special_characters if legacy_special_characters != NOT_GIVEN
         end
 
-        min_alpha = mix_case ? 2 : 0
+        min_alpha = mix_case && min_length > 1 ? 2 : 0
         temp = Lorem.characters(number: min_length, min_alpha: min_alpha)
         diff_length = max_length - min_length
 
@@ -134,7 +190,21 @@ module Faker
 
         temp
       end
+      # rubocop:enable Metrics/ParameterLists
 
+      ##
+      # Returns the domain name
+      #
+      # @return [String]
+      #
+      # @param subdomain [Bool] If true passed adds a subdomain in response
+      # @param domain [String]
+      #
+      # @example
+      #   Faker::Internet.domain_name                                       #=> "test.net"
+      #   Faker::Internet.domain_name(subdomain: true)                      #=> "test.faker.io"
+      #   Faker::Internet.domain_name(subdomain: true, domain: 'example')   #=> "faker.example.com"
+      #   Faker::Internet.domain_name(domain: 'faker')                      #=> "faker.org"
       def domain_name(legacy_subdomain = NOT_GIVEN, subdomain: false, domain: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :subdomain if legacy_subdomain != NOT_GIVEN
@@ -157,6 +227,19 @@ module Faker
         end
       end
 
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Fixes ä, ö, ü, ß characters in string passed with ae, oe, ue, ss resp.
+      #
+      # @return [String]
+      #
+      # @param string [String]
+      #
+      # @example
+      #   Faker::Internet.fix_umlauts                     #=> ""
+      #   Faker::Internet.fix_umlauts(string: 'faker')    #=> "faker"
+      #   Faker::Internet.fix_umlauts(string: 'faküer')   #=> "fakueer"
       def fix_umlauts(legacy_string = NOT_GIVEN, string: '')
         warn_for_deprecated_arguments do |keywords|
           keywords << :string if legacy_string != NOT_GIVEN
@@ -164,15 +247,40 @@ module Faker
 
         Char.fix_umlauts(string)
       end
+      # rubocop:enable Style/AsciiComments
 
+      ##
+      # Returns the domain word for internet
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.domain_word   #=> "senger"
       def domain_word
         with_locale(:en) { Char.prepare(Company.name.split(' ').first) }
       end
 
+      ## Returns the domain suffix e.g. com, org, co, biz, info etc.
+      #
+      # @return [String]
+      #
+      # @wxample
+      #   Faker::Internet.domain_suffix   #=> "com"
+      #   Faker::Internet.domain_suffix   #=> "biz"
       def domain_suffix
         fetch('internet.domain_suffix')
       end
 
+      ##
+      # Returns the MAC address
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.mac_address                   #=> "74:d0:c9:22:95:12"
+      #   Faker::Internet.mac_address(prefix: 'a')      #=> "0a:91:ce:24:89:3b"
+      #   Faker::Internet.mac_address(prefix: 'aa')     #=> "aa:38:a0:3e:e8:41"
+      #   Faker::Internet.mac_address(prefix: 'aa:44')  #=> "aa:44:30:88:6e:95"
       def mac_address(legacy_prefix = NOT_GIVEN, prefix: '')
         warn_for_deprecated_arguments do |keywords|
           keywords << :prefix if legacy_prefix != NOT_GIVEN
@@ -183,11 +291,25 @@ module Faker
         (prefix_digits + address_digits).map { |d| format('%02x', d) }.join(':')
       end
 
+      ##
+      # Returns the IPv4 address
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.ip_v4_address   #=> "97.117.128.93"
       def ip_v4_address
         [rand_in_range(0, 255), rand_in_range(0, 255),
          rand_in_range(0, 255), rand_in_range(0, 255)].join('.')
       end
 
+      ##
+      # Returns the private IPv4 address
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.private_ip_v4_address   #=> "127.120.80.42"
       def private_ip_v4_address
         addr = nil
         loop do
@@ -197,6 +319,13 @@ module Faker
         addr
       end
 
+      ##
+      # Returns the public IPv4 address
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.public_ip_v4_address   #=> "127.120.80.42"
       def public_ip_v4_address
         addr = nil
         loop do
@@ -206,6 +335,13 @@ module Faker
         addr
       end
 
+      ##
+      # Returns the private network regular expressions
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Internet.private_nets_regex  #=> [/^10\./, /^100\.(6[4-9]|[7-9]\d|1[0-1]\d|12[0-7])\./, /^127\./, /^169\.254\./, /^172\.(1[6-9]|2\d|3[0-1])\./, /^192\.0\.0\./, /^192\.168\./, /^198\.(1[8-9])\./]
       def private_nets_regex
         [
           /^10\./,                                       # 10.0.0.0    - 10.255.255.255
@@ -219,10 +355,25 @@ module Faker
         ]
       end
 
+      ##
+      # Returns lambda to check if address passed is private or not
+      #
+      # @return [Lambda]
+      #
+      # @example
+      #   Faker::Internet.private_net_checker.call("127.120.80.42")   #=> true
+      #   Faker::Internet.private_net_checker.call("148.120.80.42")   #=> false
       def private_net_checker
         ->(addr) { private_nets_regex.any? { |net| net =~ addr } }
       end
 
+      ##
+      # Returns the reserved network regular expressions
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Internet.reserved_nets_regex   #=> [/^0\./, /^192\.0\.2\./, /^192\.88\.99\./, /^198\.51\.100\./, /^203\.0\.113\./, /^(22[4-9]|23\d)\./, /^(24\d|25[0-5])\./]
       def reserved_nets_regex
         [
           /^0\./,                 # 0.0.0.0      - 0.255.255.255
@@ -235,25 +386,69 @@ module Faker
         ]
       end
 
+      ##
+      # Returns lambda function to check address passed is reserverd or not
+      #
+      # @return [Lambda]
+      #
+      # @example
+      #   Faker::Internet.reserved_net_checker.call('192.88.99.255')   #=> true
+      #   Faker::Internet.reserved_net_checker.call('192.88.199.255')  #=> false
       def reserved_net_checker
         ->(addr) { (private_nets_regex + reserved_nets_regex).any? { |net| net =~ addr } }
       end
 
+      ##
+      # Returns Ipv4 address with CIDR, range from 1 to 31
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.ip_v4_cidr  #=> "129.162.99.74/16"
+      #   Faker::Internet.ip_v4_cidr  #=> "129.162.99.74/24"
       def ip_v4_cidr
         "#{ip_v4_address}/#{rand(1..31)}"
       end
 
+      ##
+      # Returns Ipv6 address
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.ip_v6_address   #=> "7754:76d4:c7aa:7646:ea68:1abb:4055:4343"
       def ip_v6_address
         (1..8).map { rand(65_536).to_s(16) }.join(':')
       end
 
+      ##
+      # Returns Ipv6 address with CIDR, range between 1 to 127
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.ip_v6_cidr  #=> "beca:9b99:4bb6:9712:af2f:516f:8507:96e1/99"
       def ip_v6_cidr
         "#{ip_v6_address}/#{rand(1..127)}"
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Returns URL
+      #
+      # @return [String]
+      #
+      # @param host [String]
+      # @param path [String]
+      # @param scheme [String]
+      #
+      # @example
+      #   Faker::Internet.url                                                           #=> "http://sipes-okon.com/hung.macejkovic"
+      #   Faker::Internet.url(host: 'faker')                                            #=> "http://faker/shad"
+      #   Faker::Internet.url(host: 'faker', path: '/fake_test_path')                   #=> "http://faker/fake_test_path"
+      #   Faker::Internet.url(host: 'faker', path: '/fake_test_path', scheme: 'https')  #=> "https://faker/fake_test_path"
       def url(legacy_host = NOT_GIVEN, legacy_path = NOT_GIVEN, legacy_scheme = NOT_GIVEN, host: domain_name, path: "/#{username}", scheme: 'http')
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :host if legacy_host != NOT_GIVEN
           keywords << :path if legacy_path != NOT_GIVEN
@@ -262,7 +457,21 @@ module Faker
 
         "#{scheme}://#{host}#{path}"
       end
+      # rubocop:enable Metrics/ParameterLists
 
+      ##
+      # Returns unique string in URL
+      #
+      # @return [String]
+      #
+      # @param words [String] Comma or period separated words list
+      # @param glue [String] Separator to add between words passed, default used are '-' or '_'
+      #
+      # @example
+      #   Faker::Internet.slug                                    #=> "repudiandae-sed"
+      #   Faker::Internet.slug(words: 'test, faker')              #=> "test-faker"
+      #   Faker::Internet.slug(words: 'test. faker')              #=> "test-faker"
+      #   Faker::Internet.slug(words: 'test. faker', glue: '$')   #=> "test$faker"
       def slug(legacy_words = NOT_GIVEN, legacy_glue = NOT_GIVEN, words: nil, glue: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :words if legacy_words != NOT_GIVEN
@@ -273,10 +482,29 @@ module Faker
         (words || Faker::Lorem.words(number: 2).join(' ')).delete(',.').gsub(' ', glue).downcase
       end
 
+      ##
+      # Generates random token
+      #
+      # @return[String]
+      #
+      # @example
+      #   Faker::Internet.device_token  #=> "749f535671cf6b34d8e794d212d00c703b96274e07161b18b082d0d70ef1052f"
       def device_token
         shuffle(rand(16**64).to_s(16).rjust(64, '0').chars.to_a).join
       end
 
+      ##
+      # Generates the random browser identifier
+      #
+      # @return [String]
+      #
+      # @param vendor [String] Name of vendor, supported vendors are aol, chrome, firefox, internet_explorer, netscape, opera, safari
+      #
+      # @example
+      #   Faker::Internet.user_agent                    #=> "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"
+      #   Faker::Internet.user_agent(vendor: 'chrome')  #=> "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"
+      #   Faker::Internet.user_agent(vendor: 'safari')  #=> "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A"
+      #   Faker::Internet.user_agent(vendor: 'faker')   #=> "Mozilla/5.0 (Windows; U; Win 9x 4.90; SG; rv:1.9.2.4) Gecko/20101104 Netscape/9.1.0285"
       def user_agent(legacy_vendor = NOT_GIVEN, vendor: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :vendor if legacy_vendor != NOT_GIVEN
@@ -287,6 +515,13 @@ module Faker
         sample(agents)
       end
 
+      ##
+      # Generated universally unique identifier
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Internet.uuid  #=> "8a6cdd40-6d78-4fdb-912b-190e3057197f"
       def uuid
         # borrowed from: https://github.com/ruby/ruby/blob/d48783bb0236db505fe1205d1d9822309de53a36/lib/securerandom.rb#L250
         ary = Faker::Config.random.bytes(16).unpack('NnnnnN')
@@ -325,6 +560,25 @@ module Faker
       end
 
       alias user_name username
+
+      private
+
+      def sanitize_email_local_part(local_part)
+        char_range = [
+          Array('0'..'9'),
+          Array('A'..'Z'),
+          Array('a'..'z'),
+          "!#$%&'*+-/=?^_`{|}~.".split(//)
+        ].flatten
+
+        local_part.split(//).map do |char|
+          char_range.include?(char) ? char : '#'
+        end.join
+      end
+
+      def construct_email(local_part, domain_name)
+        [local_part, domain_name].join('@')
+      end
     end
   end
 end