faker 2.11.0 → 2.17.0

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
@@ -107,14 +231,30 @@ module Faker
 
         paragraph = paragraph(sentence_count: 3, supplemental: supplemental)
 
-        paragraph += ' ' + paragraph(sentence_count: 3, supplemental: supplemental) while paragraph.length < number
+        paragraph += " #{paragraph(sentence_count: 3, supplemental: supplemental)}" while paragraph.length < number
 
-        paragraph[0...number - 1] + '.'
+        "#{paragraph[0...number - 1]}."
       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

@@ -6,8 +6,24 @@ module Faker
       SUPPORTED_COLORIZATIONS = %w[red green blue].freeze
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a random image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.image #=> "https://loremflickr.com/300/300"
+      #   Faker::LoremFlickr.image(size: "50x60") #=> "https://loremflickr.com/50/60"
+      #   Faker::LoremFlickr.image(size: "50x60", search_terms: ['sports']) #=> "https://loremflickr.com/50/60/sports"
+      #   Faker::LoremFlickr.image(size: "50x60", search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/50/60/sports,fitness"
+      #   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
       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
@@ -17,9 +33,23 @@ module Faker
         build_url(size, nil, search_terms, match_all)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produces a random grayscale image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.grayscale_image #=> "https://loremflickr.com/g/300/300/all"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60") #=> "https://loremflickr.com/g/50/60/all"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60", search_terms: ['sports']) #=> "https://loremflickr.com/g/50/60/sports"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60", search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/50/60/g/sports,fitness"
+      #   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
       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
@@ -31,9 +61,23 @@ module Faker
         build_url(size, 'g', search_terms, match_all)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produces a random pixelated image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.pixelated_image #=> "https://loremflickr.com/p/300/300/all"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60") #=> "https://loremflickr.com/p/50/60/all"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60", search_terms: ['sports']) #=> "https://loremflickr.com/p/50/60/sports"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60", search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/p/50/60/sports,fitness"
+      #   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
       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
@@ -45,9 +89,24 @@ module Faker
         build_url(size, 'p', search_terms, match_all)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produces a random colorized image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param color [String] Specifies the color of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.image #=> "https://loremflickr.com/red/300/300/all"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue') #=> "https://loremflickr.com/blue/50/60/all"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue', search_terms: ['sports']) #=> "https://loremflickr.com/blue/50/60/sports"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue', search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/blue/50/60/sports,fitness"
+      #   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
       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
@@ -60,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

@@ -18,6 +18,29 @@ module Faker
                                 transport].freeze
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a random image URL from lorempixel.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param is_gray [Boolean] Determines if the image is gray.
+      # @param category [Symbol] Adds the category of the generated image to the URL.
+      # @param number [Integer] Adds a number as part of the URL.
+      # @param text [Integer] Adds dummy text as part of the URL.
+      # @param secure [Boolean] Changes the image URL between http and https.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremPixel.image #=> "https://lorempixel.com/300/300"
+      #   Faker::LoremPixel.image(size: "50x60") #=> "https://lorempixel.com/50/60"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: true) #=> "https://lorempixel.com/g/50/60"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports') #=> "https://lorempixel.com/50/60/sports"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports', number: 3) #=> "https://lorempixel.com/50/60/sports/3"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports', number: 3, text: 'Dummy-text') #=> "https://lorempixel.com/50/60/sports/3/Dummy-text"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports', number: nil, text: 'Dummy-text') #=> "https://lorempixel.com/50/60/sports/Dummy-text"
+      #   Faker::LoremPixel.image(secure: false) #=> "http://lorempixel.com/300/300"
+      #
+      # @faker.version 1.7.0
       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

@@ -3,10 +3,28 @@
 module Faker
   class Markdown < Base
     class << self
+      ##
+      # Produces a random header format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.headers #=> "##### Autem"
+      #
+      # @faker.version 1.8.0
       def headers
         "#{fetch('markdown.headers')} #{Lorem.word.capitalize}"
       end
 
+      ##
+      # Produces a random emphasis formatting on a random word in two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.emphasis #=> "_Incidunt atque quis repellat id impedit.  Quas numquam quod incidunt dicta non. Blanditiis delectus laudantium atque reiciendis qui._"
+      #
+      # @faker.version 1.8.0
       def emphasis
         paragraph = Faker::Lorem.paragraph(sentence_count: 3)
         words = paragraph.split(' ')
@@ -16,6 +34,15 @@ module Faker
         words.join(' ')
       end
 
+      ##
+      # Produces a random ordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.ordered_list #=> "1. Qui reiciendis non consequatur atque.\n2. Quo doloremque veritatis tempora aut.\n3. Aspernatur.\n4. Ea ab.\n5. Qui.\n6. Sit pariatur nemo eveniet.\n7. Molestiae aut.\n8. Nihil molestias iure placeat.\n9. Dolore autem quisquam."
+      #
+      # @faker.version 1.8.0
       def ordered_list
         number = rand(1..10)
 
@@ -26,6 +53,15 @@ module Faker
         result.join('')
       end
 
+      ##
+      # Produces a random unordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.unordered_list #=> "* Voluptatum aliquid tempora molestiae facilis non sed.\n* Nostrum omnis iste impedit voluptatum dolor.\n* Esse quidem et facere."
+      #
+      # @faker.version 1.8.0
       def unordered_list
         number = rand(1..10)
 
@@ -36,14 +72,41 @@ module Faker
         result.join('')
       end
 
+      ##
+      # Produces a random inline code snippet between two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.inline_code #=> "Aut eos quis suscipit. `Dignissimos voluptatem expedita qui.` Quo doloremque veritatis tempora aut."
+      #
+      # @faker.version 1.8.0
       def inline_code
         "`#{Faker::Lorem.sentence(word_count: 1)}`"
       end
 
+      ##
+      # Produces a random code block formatted in Ruby.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.block_code #=> "```ruby\nEos quasi qui.\n```"
+      #
+      # @faker.version 1.8.0
       def block_code
         "```ruby\n#{Lorem.sentence(word_count: 1)}\n```"
       end
 
+      ##
+      # Produces a random 3x4 table with a row of headings, a row of hyphens and two rows of data
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.table #=> "ad | similique | voluptatem\n---- | ---- | ----\ncorrupti | est | rerum\nmolestiae | quidem | et"
+      #
+      # @faker.version 1.8.0
       def table
         table = []
         3.times do
@@ -53,12 +116,40 @@ module Faker
         table.join("\n")
       end
 
+      ##
+      # 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.
+      #
+      # @return [String, Array<String>]
+      #
+      # @example
+      #   Faker::Markdown.random #=> returns output from a single method outlined above
+      #   Faker::Markdown.random("table") #=> returns output from any single method outlined above except for "table"
+      #   Faker::Markdown.random("ordered_list", "unordered_list") #=> returns output from any single method outlined above except for either ordered_list and unordered_list
+      #
+      # @faker.version 1.8.0
       def random(*args)
         method_list = available_methods
         args&.each { |ex| method_list.delete_if { |meth| meth == ex.to_sym } }
         send(method_list[rand(0..method_list.length - 1)])
       end
 
+      ##
+      # Produces a simulated blog-esque text-heavy block in markdown
+      #
+      # Keyword arguments: sentences, repeat
+      # @param sentences [Integer] Specifies how many sentences make a text block.
+      # @param repeat [Integer] Specifies how many times the text block repeats.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.sandwich #=> returns newline separated content of 1 header, 1 default lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 5) #=> returns newline separated content of 1 header, 1 5-sentence lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 6, repeat: 3) #=> returns newline separated content of 1 header, and then 3 sections consisting of, here, 1 6-sentence lorem paragraph and 1 random markdown element. The random markdown element is chosen at random in each iteration of the paragraph-markdown pairing.
+      #
+      # @faker.version 1.8.0
       def sandwich(legacy_sentences = NOT_GIVEN, legacy_repeat = NOT_GIVEN, sentences: 3, repeat: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :sentences if legacy_sentences != NOT_GIVEN

data/lib/faker/default/measurement.rb

@@ -6,6 +6,19 @@ module Faker
       ALL = 'all'
       NONE = 'none'
 
+      ##
+      # Produces a random height measurement.
+      #
+      # @param amount [Integer] Speficies the random height value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.height #=> "6 inches"
+      #   Faker::Measurement.height(amount: 1.4) #=> "1.4 inches"
+      #   Faker::Measurement.height(amount: "none") #=> "inch"
+      #   Faker::Measurement.height(amount: "all") #=> "inches"
+      #
+      # @faker.version 1.7.3
       def height(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -14,6 +27,17 @@ module Faker
         define_measurement_locale(amount, 'height')
       end
 
+      ##
+      # Produces a random length measurement.
+      #
+      # @param amount [Integer] Speficies the random length value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.length #=> "1 yard"
+      #   Faker::Measurement.length(amount: 1.4) #=> "1.4 yards"
+      #
+      # @faker.version 1.7.3
       def length(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -22,6 +46,17 @@ module Faker
         define_measurement_locale(amount, 'length')
       end
 
+      ##
+      # Produces a random volume measurement.
+      #
+      # @param amount [Integer] Speficies the random volume value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.volume #=> "10 cups"
+      #   Faker::Measurement.volume(amount: 1.4) #=> "1.4 cups"
+      #
+      # @faker.version 1.7.3
       def volume(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -30,6 +65,17 @@ module Faker
         define_measurement_locale(amount, 'volume')
       end
 
+      ##
+      # Produces a random weight measurement.
+      #
+      # @param amount [Integer] Speficies the random weight value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.weight #=> "3 pounds"
+      #   Faker::Measurement.weight(amount: 1.4) #=> "1.4 pounds"
+      #
+      # @faker.version 1.7.3
       def weight(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -38,6 +84,17 @@ module Faker
         define_measurement_locale(amount, 'weight')
       end
 
+      ##
+      # Produces a random metric height measurement.
+      #
+      # @param amount [Integer] Speficies the random height value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_height #=> "2 meters"
+      #   Faker::Measurement.metric_height(amount: 1.4) #=> "1.4 meters"
+      #
+      # @faker.version 1.7.3
       def metric_height(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -46,6 +103,17 @@ module Faker
         define_measurement_locale(amount, 'metric_height')
       end
 
+      ##
+      # Produces a random metric length measurement.
+      #
+      # @param amount [Integer] Speficies the random length value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_length #=> "0 decimeters"
+      #   Faker::Measurement.metric_length(amount: 1.4) #=> "1.4 decimeters"
+      #
+      # @faker.version 1.7.3
       def metric_length(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -54,6 +122,17 @@ module Faker
         define_measurement_locale(amount, 'metric_length')
       end
 
+      ##
+      # Produces a random metric volume measurement.
+      #
+      # @param amount [Integer] Speficies the random volume value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_volume #=> "1 liter"
+      #   Faker::Measurement.metric_volume(amount: 1.4) #=> "1.4 liters"
+      #
+      # @faker.version 1.7.3
       def metric_volume(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -62,6 +141,17 @@ module Faker
         define_measurement_locale(amount, 'metric_volume')
       end
 
+      ##
+      # Produces a random metric weight measurement.
+      #
+      # @param amount [Integer] Speficies the random weight value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_weight #=> "8 grams"
+      #   Faker::Measurement.metric_weight(amount: 1.4) #=> "1.4 grams"
+      #
+      # @faker.version 1.7.3
       def metric_weight(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -82,9 +172,10 @@ module Faker
 
       def define_measurement_locale(amount, locale)
         ensure_valid_amount(amount)
-        if amount == ALL
+        case amount
+        when ALL
           make_plural(fetch("measurement.#{locale}"))
-        elsif amount == NONE
+        when NONE
           fetch("measurement.#{locale}")
         else
           locale = check_for_plural(fetch("measurement.#{locale}"), amount)