Add YARD docs to Faker::Chile_Rut (faker-ruby#2054)

* Add YARD docs to Faker::Chile_Rut

* Remove non-ascii characters from YARD

doc/default/business.md

@@ -1,9 +1,25 @@
 # Faker::Business
 
 ```ruby
-Faker::Business.credit_card_number #=> "1228-1221-1221-1431"
-
 Faker::Business.credit_card_expiry_date #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
 
-Faker::Business.credit_card_type #=> "visa"
+Faker::Business.card_brand #=> "visa"
+
+Faker::Business.card_type #=> "visa_debit"
+
+# Keyword arguments: card_type
+Faker::Business.valid_card_number #=> "4242424242424242"
+Faker::Business.valid_card_number(card_type: "visa_debit") #=> "4000056655665556"
+
+# Keyword arguments: card_error
+Faker::Business.invalid_card_number #=> "4000000000000002"
+Faker::Business.invalid_card_number(card_error: "addressZipFail") #=> "4000000000000010"
+
+Faker::Business.card_expiry_month #=> "10"
+
+Faker::Business.card_expiry_year #=> "2023" # This will always be a year in the future
+
+# Keyword arguments: card_type
+Faker::Business.ccv #=> "123"
+Faker::Business.ccv(card_type: "amex") #=> "1234"
 ```

doc/default/stripe.md

@@ -1,27 +1,11 @@
 # Faker::Stripe
 
-Test Stripe transactions without hardcoding card numbers and tokens
+Test Stripe transactions without hardcoding tokens
 
 ```ruby
-# Keyword arguments: card_type
-Faker::Stripe.valid_card #=> "4242424242424242"
-Faker::Stripe.valid_card(card_type: "visa_debit") #=> "4000056655665556"
-
 # Keyword arguments: card_type
 Faker::Stripe.valid_token #=> "tok_visa"
 Faker::Stripe.valid_token(card_type: "mc_debit") #=> "tok_mastercard_debit"
-
-# Keyword arguments: card_error
-Faker::Stripe.invalid_card #=> "4000000000000002"
-Faker::Stripe.invalid_card(card_error: "addressZipFail") #=> "4000000000000010"
-
-Faker::Stripe.month #=> "10"
-
-Faker::Stripe.year #=> "2018" # This will always be a year in the future
-
-# Keyword arguments: card_type
-Faker::Stripe.ccv #=> "123"
-Faker::Stripe.ccv(card_type: "amex") #=> "1234"
 ```
 
 ProTip:

lib/faker/default/business.rb

@@ -8,16 +8,16 @@ class Business < Base
 
     class << self
       ##
-      # Produces a credit card number.
+      # Produces a card expiration date.
       #
-      # @return [String]
+      # @return [Date]
       #
       # @example
-      #   Faker::Business.credit_card_number #=> "1228-1221-1221-1431"
+      #   Faker::Business.card_expiry_date #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
       #
-      # @faker.version 1.2.0
-      def credit_card_number
-        fetch('business.credit_card_numbers')
+      # @faker.version 2.13.0
+      def card_expiry_date
+        ::Date.today + (365 * rand(1..4))
       end
 
       ##
@@ -28,9 +28,49 @@ def credit_card_number
       # @example
       #   Faker::Business.credit_card_expiry_date #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
       #
+      # @deprecated Use the card_expiry_date method instead.
+      #
       # @faker.version 1.2.0
-      def credit_card_expiry_date
-        ::Date.today + (365 * rand(1..4))
+      alias credit_card_expiry_date card_expiry_date
+
+      ##
+      # Produces a random card expiry month in two digits format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.card_expiry_month #=> "10"
+      #
+      # @faker.version 2.13.0
+      def card_expiry_month
+        format('%02d', rand_in_range(1, 12))
+      end
+
+      ##
+      # Produces a random card expiry year that is always in the future.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.card_expiry_year #=> "2023" # This will always be a year in the future
+      #
+      # @faker.version 2.13.0
+      def card_expiry_year
+        start_year = ::Time.new.year + 1
+        rand_in_range(start_year, start_year + 3).to_s
+      end
+
+      ##
+      # Produces a type of a card.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.card_type #=> "visa_debit"
+      #
+      # @faker.version 1.2.0
+      def card_type
+        sample(translate('faker.business.valid_cards').keys).to_s
       end
 
       ##
@@ -41,9 +81,119 @@ def credit_card_expiry_date
       # @example
       #   Faker::Business.credit_card_type #=> "visa"
       #
+      # @deprecated Use the card_type method instead.
+      #
       # @faker.version 1.2.0
-      def credit_card_type
-        fetch('business.credit_card_types')
+      alias credit_card_type card_type
+
+      ##
+      # Produces a brand of a card.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.card_brand #=> "visa"
+      #
+      # @faker.version 2.13.0
+      def card_brand
+        fetch('business.card_brands')
+      end
+
+      ##
+      # Produces a random valid card number.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.valid_card_number #=> "4242424242424242"
+      #   Faker::Business.valid_card_number(card_type: "visa_debit") #=> "4000056655665556"
+      #
+      # @faker.version 2.13.0
+      def valid_card_number(legacy_card_type = NOT_GIVEN, card_type: nil)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_type if legacy_card_type != NOT_GIVEN
+        end
+
+        valid_cards = translate('faker.business.valid_cards').keys
+
+        if card_type.nil?
+          card_type = sample(valid_cards).to_s
+        else
+          unless valid_cards.include?(card_type.to_sym)
+            raise ArgumentError,
+                  "Valid credit cards argument can be left blank or include #{valid_cards.join(', ')}"
+          end
+        end
+
+        fetch('business.valid_cards.' + card_type)
+      end
+
+      ##
+      # Produces a random valid card number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.credit_card_number #=> "1228-1221-1221-1431"
+      #
+      # @deprecated Use the valid_card_number method instead.
+      #
+      # @faker.version 1.2.0
+      def credit_card_number
+        credit_card_type = Faker::Base.sample(%w[visa mc amex discover diners_club jcb])
+        credit_card_number_without_hyphens = valid_card_number(card_type: credit_card_type)
+        (1...3).reduce(credit_card_number_without_hyphens.to_s) do |card_number, index|
+          card_number.insert(index * 4, '-')
+        end
+      end
+
+      ##
+      # Produces a random invalid card number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.invalid_card_number #=> "4000000000000002"
+      #   Faker::Business.invalid_card_number(card_error: "addressZipFail") #=> "4000000000000010"
+      #
+      # @faker.version 2.13.0
+      def invalid_card_number(legacy_card_error = NOT_GIVEN, card_error: nil)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_error if legacy_card_error != NOT_GIVEN
+        end
+
+        invalid_cards = translate('faker.business.invalid_cards').keys
+
+        if card_error.nil?
+          card_error = sample(invalid_cards).to_s
+        else
+          unless invalid_cards.include?(card_error.to_sym)
+            raise ArgumentError,
+                  "Invalid credit cards argument can be left blank or include #{invalid_cards.join(', ')}"
+          end
+        end
+
+        fetch('business.invalid_cards.' + card_error)
+      end
+
+      ##
+      # Produces a random ccv number.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.ccv #=> "123"
+      #   Faker::Business.ccv(card_type: "amex") #=> "1234"
+      #
+      # @faker.version 2.13.0
+      def ccv(legacy_card_type = NOT_GIVEN, card_type: nil)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_type if legacy_card_type != NOT_GIVEN
+        end
+
+        (card_type.to_s == 'amex' ? rand_in_range(1000, 9999) : rand_in_range(100, 999)).to_s
       end
     end
   end

lib/faker/default/chile_rut.rb

@@ -5,7 +5,19 @@ class ChileRut < Base
     class << self
       @last_rut = nil
 
-      # Fixed param added for testing a specific RUT and check digit combination.
+      ##
+      # Produces a random Chilean RUT (Rol Unico Tributario, ID with 8 digits).
+      #
+      # @param min_rut [Integer] Specifies the minimum value of the rut.
+      # @param fixed [Boolean] Determines if the rut is fixed (returns the min_rut value).
+      # @return [Number]
+      #
+      # @example
+      #   Faker::ChileRut.rut #=> 11235813
+      #   Faker::ChileRut.rut(min_rut: 20890156) #=> 31853211
+      #   Faker::ChileRut.rut(min_rut: 20890156, fixed: true) #=> 20890156
+      #
+      # @faker.version 1.9.2
       def rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 1, fixed: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_rut if legacy_min_rut != NOT_GIVEN
@@ -15,6 +27,15 @@ def rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 1, fixed:
         @last_rut = fixed ? min_rut : rand_in_range(min_rut, 99_999_999)
       end
 
+      ##
+      # Produces a random Chilean digito verificador (check-digit).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChileRut.dv #=> "k"
+      #
+      # @faker.version 1.9.2
       def dv
         split_reversed_rut = @last_rut.to_s.reverse.split('')
         seq = [2, 3, 4, 5, 6, 7]
@@ -34,11 +55,33 @@ def dv
         end
       end
 
+      ##
+      # Produces a random Chilean digito verificador (check-digit).
       # Alias for english speaking devs.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChileRut.check_digit #=> "5"
+      #
+      # @faker.version 1.9.2
       def check_digit
         dv
       end
 
+      ##
+      # Produces a random Chilean RUT (Rol Unico Tributario, ID with 8 digits) with a dv (digito verificador, check-digit).
+      #
+      # @param min_rut [Integer] Specifies the minimum value of the rut.
+      # @param fixed [Boolean] Determines if the rut is fixed (returns the min_rut value).
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChileRut.full_rut #=> "30686957-4"
+      #   Faker::ChileRut.full_rut(min_rut: 20890156) #=> "30686957-4"
+      #   Faker::ChileRut.full_rut(min_rut: 30686957, fixed: true) #=> "30686957-4"
+      #
+      # @faker.version 1.9.2
       def full_rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 0, fixed: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_rut if legacy_min_rut != NOT_GIVEN