Add YARD docs to Faker::Types (#1999)

* Add YARD docs to Faker::Types

* Update array documentation to reflect parameter

doc/default/types.md

@@ -23,7 +23,8 @@ Faker::Types.complex_rb_hash(number: 1) #=> {user: {first: "bob", last: "marley"
 Faker::Types.complex_rb_hash(number: 2) #=> {user: {first: "bob", last: "marley"}, son: ["damien", "marley"]}
 
 # Random Array
-Faker::Types.rb_array #=> ["a", 1, 2, "bob"]
+Faker::Types.rb_array #=> ["a"]
+Faker::Types.rb_array(len: 4) #=> ["a", 1, 2, "bob"]
 
 # Random Type (string, or integer)
 Faker::Types.random_type #=> 1 or "a" or "bob"

lib/faker/default/types.rb

@@ -7,6 +7,15 @@ class Types < Base
     COMPLEX_TYPES = %i[hash array].freeze
 
     class << self
+      ##
+      # Produces a random String created from word (Faker::Lorem.word)
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Types.rb_string #=> "foobar"
+      #
+      # @faker.version 1.8.6
       def rb_string(legacy_words = NOT_GIVEN, words: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :words if legacy_words != NOT_GIVEN
@@ -20,10 +29,28 @@ def rb_string(legacy_words = NOT_GIVEN, words: 1)
         shuffle(word_list)[0, resolved_num].join(' ')
       end
 
+      ##
+      # Produces a random character from the a-z, 0-9 ranges.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Types.character #=> "n"
+      #
+      # @faker.version 1.8.6
       def character
         sample(CHARACTERS)
       end
 
+      ##
+      # Produces a random integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Types.rb_integer #=> 1
+      #
+      # @faker.version 1.8.6
       def rb_integer(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 0, to: 100)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -33,6 +60,18 @@ def rb_integer(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 0, to: 100)
         rand(from..to).to_i
       end
 
+      ##
+      # Produces a random hash with random keys and values.
+      #
+      # @param number [Integer] Specifies the number of key-value pairs.
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Types.rb_hash #=> {name: "bob"}
+      #   Faker::Types.rb_hash(number: 1) #=> {name: "bob"}
+      #   Faker::Types.rb_hash(number: 2) #=> {name: "bob", last: "marley"}
+      #
+      # @faker.version 1.8.6
       def rb_hash(legacy_number = NOT_GIVEN, legacy_type = NOT_GIVEN, number: 1, type: random_type)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -46,6 +85,18 @@ def rb_hash(legacy_number = NOT_GIVEN, legacy_type = NOT_GIVEN, number: 1, type:
         end
       end
 
+      ##
+      # Produces a random complex hash with random keys and values where the values may include other hashes and arrays.
+      #
+      # @param number [Integer] Specifies the number of key-value pairs.
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Types.complex_rb_hash #=> {user: {first: "bob", last: "marley"}}
+      #   Faker::Types.complex_rb_hash(number: 1) #=> {user: {first: "bob", last: "marley"}}
+      #   Faker::Types.complex_rb_hash(number: 2) #=> {user: {first: "bob", last: "marley"}, son: ["damien", "marley"]}
+      #
+      # @faker.version 1.8.6
       def complex_rb_hash(legacy_number = NOT_GIVEN, number: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -54,6 +105,17 @@ def complex_rb_hash(legacy_number = NOT_GIVEN, number: 1)
         rb_hash(number: number, type: random_complex_type)
       end
 
+      ##
+      # Produces a random array.
+      #
+      # @param len [Integer] Specifies the number of elements in the array.
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Types.rb_array #=> ["a"]
+      #   Faker::Types.rb_array(len: 4) #=> ["a", 1, 2, "bob"]
+      #
+      # @faker.version 1.8.6
       def rb_array(legacy_len = NOT_GIVEN, len: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :len if legacy_len != NOT_GIVEN
@@ -66,6 +128,15 @@ def rb_array(legacy_len = NOT_GIVEN, len: 1)
         end
       end
 
+      ##
+      # Produces a random type that's either a String or an Integer.
+      #
+      # @return [String, Integer]
+      #
+      # @example
+      #   Faker::Types.random_type #=> 1 or "a" or "bob"
+      #
+      # @faker.version 1.8.6
       def random_type
         type_to_use = SIMPLE_TYPES[rand(0..SIMPLE_TYPES.length - 1)]
         case type_to_use
@@ -76,6 +147,15 @@ def random_type
         end
       end
 
+      ##
+      # Produces a random complex type that's either a String, an Integer, an array or a hash.
+      #
+      # @return [String, Integer]
+      #
+      # @example
+      #   Faker::Types.random_complex_type #=> 1 or "a" or "bob" or {foo: "bar"}
+      #
+      # @faker.version 1.8.6
       def random_complex_type
         types = SIMPLE_TYPES + COMPLEX_TYPES
         type_to_use = types[rand(0..types.length - 1)]