faker 2.7.0 → 2.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cacd4170df63c267efee25b7e575509b1ff16528a143a916e90c6381bd48a8b
-  data.tar.gz: 7165d20574c9994f703d6c5b473b42125c27421754c7e387e3d34d5c174307e7
+  metadata.gz: f748d0be9910a52b4c0f7ca9731c0d604a92d00a73a4ce8a47610cde547d7027
+  data.tar.gz: 4c02b2ab5e03424e9a7271aae8b5cc45358c2e9e1ac79ef9a43b3c6c97bd2151
 SHA512:
-  metadata.gz: 5fc24fc4438f8737f09597f0f8b7be162f5d609c3e8b7799423eae173635d0762688f51e4790e915913e6e263ba9dbb45f6f02829f4ff5cf1fab724e4118acbd
-  data.tar.gz: ca6e471b882bca1b98ab777d6dfdf8798f4cb061d4c98781a8e93869d979ba8eefdf98541387fa309d745cd67fcb5a91b7adc8a23f647da3c8a705291b5f1989
+  metadata.gz: 5e7fd5141e00c96959a05b874f1a972a29772803eb76fec01c78b368755bbe688cd9995276e3145dbd943b723d58eec4234a87152c898aedd5c634b26af9a7c0
+  data.tar.gz: af823f7fafa1f532c97d99afbc934b922727f64ee9094fe1c97309c82faa63be66501b91716f3340a7aa32b7378a685d78f65847b9d4b3a1dbe008f21b40f0f8

data/CHANGELOG.md

@@ -1,5 +1,170 @@
 # Change Log
 
+## [v2.10.1](https://github.com/faker-ruby/faker/tree/v2.10.1) (2020-01-13)
+
+This version:
+- fixes locales
+- updates local dependencies
+- fixes warnings
+
+## Bug/Fixes
+
+- [PR #1868](https://github.com/faker-ruby/faker/pull/1868) Fix a deprecation warning in unique_generator.rb related to the kwarg [@connorshea](https://github.com/connorshea)
+
+## Update Locales
+
+- [PR #1800](https://github.com/faker-ruby/faker/pull/1800) Update diners_club and jcb test cards since they were updated in String [@santib](https://github.com/santib)
+- [PR #1879](https://github.com/faker-ruby/faker/pull/1879) Field changes in da-DK locale [@psibi](https://github.com/psibi)
+- [PR #1878](https://github.com/faker-ruby/faker/pull/1878) Fix name related files in ca locale [@psibi](https://github.com/psibi)
+- [PR #1877](https://github.com/faker-ruby/faker/pull/1877) Fix the path names for bg.yml [@psibi](https://github.com/psibi)
+
+## Update local dependencies
+
+Allow all versions of i18n from 1.6 up to 2 (#1894) [@orien](https://github.com/orien)
+Update minitest requirement from = 5.13.0 to = 5.14.0 (#1904)
+Bump i18n from 1.8.1 to 1.8.2 (#1905)
+Bump i18n from 1.8.0 to 1.8.1 (#1895)
+Update i18n requirement from >= 1.6, < 1.8 to >= 1.6, < 1.9 (#1893)
+Update yard requirement from = 0.9.23 to = 0.9.24 (#1892)
+Update rubocop requirement from = 0.78.0 to = 0.79.0 (#1890)
+Update yard requirement from = 0.9.22 to = 0.9.23 (#1889)
+Update yard requirement from = 0.9.20 to = 0.9.22 (#1882)
+
+------------------------------------------------------------------------------
+
+## [v2.10.0](https://github.com/faker-ruby/faker/tree/v2.10.0) (2019-12-28)
+
+This version:
+- adds `Faker::Address.mail_box`
+- adds YARD docs
+- fix Ruby 2.7 warnings
+- adds other minor changes
+
+## Bug/Fixes
+
+- [PR #1876](https://github.com/faker-ruby/faker/pull/1876) Fix Ruby 2.7 deprecation warnings for the translate method. [@connorshea](https://github.com/connorshea)
+- [PR #1867](https://github.com/faker-ruby/faker/pull/1867) Fix tests failing on Ruby 2.7 [@connorshea](https://github.com/connorshea)
+
+## Chores
+
+- [PR #1866](https://github.com/faker-ruby/faker/pull/1866) Upgrade the Gemfile.lock to Bundler 2. [@connorshea](https://github.com/connorshea)
+
+## Documentation
+
+- [PR #1873](https://github.com/faker-ruby/faker/pull/1873) Add YARD docs for `Faker::Music{,::Opera}` [@jas14](https://github.com/jas14)
+- [PR #1862](https://github.com/faker-ruby/faker/pull/1862) Update phone number documentation [@aVigorousDev](https://github.com/aVigorousDev)
+
+## Feature Request
+
+- [PR #1875](https://github.com/faker-ruby/faker/pull/1875) Add Ruby 2.7 to the CI test matrix. [@connorshea](https://github.com/connorshea)
+- [PR #1568](https://github.com/faker-ruby/faker/pull/1568) Add `Faker::Address.mail_box` and some NZ locale updates [@mermop](https://github.com/mermop)
+
+## Refactoring
+
+- [PR #1874](https://github.com/faker-ruby/faker/pull/1874) Extract constants in `Faker::Music` [@jas14](https://github.com/jas14)
+
+## Update local dependencies
+
+Update rubocop requirement from = 0.77.0 to = 0.78.0 (#1869)
+
+------------------------------------------------------------------------------
+
+## [v2.9.0](https://github.com/faker-ruby/faker/tree/v2.9.0) (2019-12-16)
+
+This version:
+- adds `Faker::Gender.short_binary_type`
+- adds a few YARD docs
+- fix Faker::Educator issues
+- update locales
+
+## Bug/Fixes
+
+- [PR #1860](https://github.com/faker-ruby/faker/pull/1860) Fix Educator methods returning bad data. [@connorshea](https://github.com/connorshea)
+
+## Documentation
+
+- [PR #1859](https://github.com/faker-ruby/faker/pull/1859) YYYY-MM-DD in CHANGELOG [@jas14](https://github.com/jas14)
+- [PR #1797](https://github.com/faker-ruby/faker/pull/1797) add YARD doc for Faker::Job [@ashishra0](https://github.com/ashishra0)
+- [PR #1790](https://github.com/faker-ruby/faker/pull/1790) add Faker::Beer YARD docs [@ashishra0](https://github.com/ashishra0)
+
+## Feature Request
+
+- [PR #1863](https://github.com/faker-ruby/faker/pull/1863) Add Faker::Gender.short_binary_type [@bruno-b-martins](https://github.com/bruno-b-martins)
+
+## Update locales
+
+- [PR #1864](https://github.com/faker-ruby/faker/pull/1864) adding `male` & `female` first names for persian [@alphamarket](https://github.com/alphamarket)
+
+------------------------------------------------------------------------------
+
+## [v2.8.1](https://github.com/faker-ruby/faker/tree/v2.8.1) (2019-12-06)
+
+## Bug/Fixes
+
+- [PR #1846](https://github.com/faker-ruby/faker/pull/1846) Fix internet custom domain with suffix [@ngouy](https://github.com/ngouy)
+
+## Documentation
+
+- [PR #1852](https://github.com/faker-ruby/faker/pull/1852) Add YARD docs for Faker::Business. [@connorshea](https://github.com/connorshea)
+- [PR #1851](https://github.com/faker-ruby/faker/pull/1851) Add YARD docs for Faker::Crypto. [@connorshea](https://github.com/connorshea)
+- [PR #1850](https://github.com/faker-ruby/faker/pull/1850) Add YARD docs for Faker::Kpop. [@connorshea](https://github.com/connorshea)
+- [PR #1849](https://github.com/faker-ruby/faker/pull/1849) Add YARD docs for Faker::BossaNova. [@connorshea](https://github.com/connorshea)
+- [PR #1848](https://github.com/faker-ruby/faker/pull/1848) Add YARD Docs for Faker::Demographic. [@connorshea](https://github.com/connorshea)
+- [PR #1844](https://github.com/faker-ruby/faker/pull/1844) Fix yard doc in contribution [@vikas95prasad](https://github.com/vikas95prasad)
+- [PR #1802](https://github.com/faker-ruby/faker/pull/1802) Add YARD doc for Faker::Food [@sap1enza](https://github.com/sap1enza)
+- [PR #1766](https://github.com/faker-ruby/faker/pull/1766) Add YARD docs for Faker::Address [@connorshea](https://github.com/connorshea)
+
+## Refactoring
+
+- [PR #1847](https://github.com/faker-ruby/faker/pull/1847) Makes minor refactors on Internet.domain_name method [@tiagofsilva](https://github.com/tiagofsilva)
+- [PR #1772](https://github.com/faker-ruby/faker/pull/1848) Refactor Faker::Educator and add docs [@connorshea](https://github.com/connorshea)
+
+## Update local dependencies
+
+- Update rubocop requirement from = 0.76.0 to = 0.77.0 (#1843)
+
+------------------------------------------------------------------------------
+
+## [v2.8.0](https://github.com/faker-ruby/faker/tree/v2.8.0) (2019-12-01)
+
+## Bug/Fixes
+
+- [PR #1563](https://github.com/faker-ruby/faker/pull/1563)
+Fix generating routing number [@psienko](https://github.com/psienko)
+
+## Chores
+
+- [PR #1835](https://github.com/faker-ruby/faker/pull/1835)
+Remove duplicate method description [@pacso](https://github.com/pacso)
+
+## Documentation
+
+- [PR #1837](https://github.com/faker-ruby/faker/pull/1837)
+docs: Internet #email, #domain do not control TLD [@olleolleolle](https://github.com/olleolleolle)
+- [PR #1833](https://github.com/faker-ruby/faker/pull/1833) Explain safe_email method [@swrobel](https://github.com/swrobel)
+- [PR #1810](https://github.com/faker-ruby/faker/pull/1810) Add yard docs for Faker::Coffee methods [@LuanGB](https://github.com/LuanGB)
+- [PR #1803](https://github.com/faker-ruby/faker/pull/1803)
+add YARD doc for Faker::Coin [@sap1enza](https://github.com/sap1enza) [@connorshea](https://github.com/connorshea)
+- [PR #1799](https://github.com/faker-ruby/faker/pull/1799) Remove 'See below examples' for consistency [@DevUsmanGhani](https://github.com/DevUsmanGhani)
+- [PR #1793](https://github.com/faker-ruby/faker/pull/1793) add Faker::Relationship YARD docs [@DevUsmanGhani](https://github.com/DevUsmanGhani)
+
+## Feature Request
+
+- [PR #1808](https://github.com/faker-ruby/faker/pull/1808) Adds domain option for Internet email and domain_name methods [@tiagofsilva](https://github.com/tiagofsilva)
+
+## Update locales
+
+- [PR #1841](https://github.com/faker-ruby/faker/pull/1841)
+Fix strange result from `Lorem.word` in ja locale [@yujideveloper](https://github.com/yujideveloper)
+- [PR #1839](https://github.com/faker-ruby/faker/pull/1839)
+added new heroes, new maps and almost all of the quotes [@TCsTheMechanic](https://github.com/TCsTheMechanic)
+
+## Update local dependencies
+
+- [PR #1831](https://github.com/faker-ruby/faker/pull/1831) Update rake requirement from = 13.0.0 to = 13.0.1 [@DevUsmanGhani](https://github.com/DevUsmanGhani)
+
+------------------------------------------------------------------------------
+
 ## [v2.7.0](https://github.com/faker-ruby/faker/tree/v2.7.0) (2019-11-01)
 
 This version:
@@ -57,7 +222,7 @@ The following development dependencies were updated:
 
 ------------------------------------------------------------------------------
 
-## [v2.5.0](https://github.com/faker-ruby/faker/tree/v2.5.0) (2019-30-09)
+## [v2.5.0](https://github.com/faker-ruby/faker/tree/v2.5.0) (2019-09-30)
 
 This version introduces:
 - locales for Thai language - the mother language in Thailand
@@ -91,7 +256,7 @@ The following development dependencies were updated:
 
 ------------------------------------------------------------------------------
 
-## [v2.4.0](https://github.com/faker-ruby/faker/tree/v2.4.0) (2019-19-09)
+## [v2.4.0](https://github.com/faker-ruby/faker/tree/v2.4.0) (2019-09-19)
 
 ## Documentation
 
@@ -116,7 +281,7 @@ The following development dependencies were updated:
 
 ------------------------------------------------------------------------------
 
-## [v2.3.0](https://github.com/faker-ruby/faker/tree/v2.3.0) (2019-12-09)
+## [v2.3.0](https://github.com/faker-ruby/faker/tree/v2.3.0) (2019-09-12)
 
 ## Documentation
 
@@ -135,7 +300,7 @@ The following development dependencies were updated:
 
 ------------------------------------------------------------------------------
 
-## [v2.2.2](https://github.com/faker-ruby/faker/tree/v2.2.2) (2019-05-09)
+## [v2.2.2](https://github.com/faker-ruby/faker/tree/v2.2.2) (2019-09-05)
 
 ## Bug/Fixes
 
@@ -159,7 +324,7 @@ The following development dependencies were updated:
 
 ------------------------------------------------------------------------------
 
-## [v2.2.1](https://github.com/faker-ruby/faker/tree/v2.2.1) (2019-30-08)
+## [v2.2.1](https://github.com/faker-ruby/faker/tree/v2.2.1) (2019-08-30)
 
 ## Bug/Fixes
 
@@ -169,7 +334,7 @@ The following development dependencies were updated:
 
 Fixing number with one digit caused the test_insignificant_zero to fail. As it seemed that the behavior tested by test_insignificant_zero was already covered by test_number and test_decimal, we removed it to prevent duplication.
 
-## [v2.2.0](https://github.com/faker-ruby/faker/tree/v2.2.0) (2019-25-08)
+## [v2.2.0](https://github.com/faker-ruby/faker/tree/v2.2.0) (2019-08-25)
 
 ## Deprecate
 
@@ -193,7 +358,7 @@ Add deprecation warning for positional arguments to notify users that are coming
 
 ------------------------------------------------------------------------------
 
-## [v2.1.2](https://github.com/faker-ruby/faker/tree/v2.1.2) (2019-10-08)
+## [v2.1.2](https://github.com/faker-ruby/faker/tree/v2.1.2) (2019-08-10)
 
 ## Enhancements
 
@@ -203,7 +368,7 @@ Add deprecation warning for positional arguments to notify users that are coming
 
 We had to use `bundled with 1.7.3` to avoid some issues.
 
-## [v2.1.1](https://github.com/faker-ruby/faker/tree/2.1.1) (2019-10-08)
+## [v2.1.1](https://github.com/faker-ruby/faker/tree/2.1.1) (2019-08-10)
 
 ## Bug/Fixes
 
@@ -221,7 +386,7 @@ Rollback Faker::Time changes because we should expect the date format from activ
 
 ------------------------------------------------------------------------------
 
-## [v2.1.0](https://github.com/faker-ruby/faker/tree/v2.1.0) (2019-31-07)
+## [v2.1.0](https://github.com/faker-ruby/faker/tree/v2.1.0) (2019-07-31)
 
 ## Bug/Fixes
 - [PR #1675](https://github.com/faker-ruby/faker/pull/1675) Fix off-by-one error when formatting month names [@jutonz](https://github.com/jutonz)
@@ -230,7 +395,7 @@ This change required a quick release because it's a breaking issue. Every place
 
 ------------------------------------------------------------------------------
 
-## [v2.0](https://github.com/faker-ruby/faker/tree/v2.0) (2019-31-07)
+## [v2.0](https://github.com/faker-ruby/faker/tree/v2.0) (2019-07-31)
 
 ## Important Note:
 

data/README.md

@@ -43,7 +43,7 @@ development.
 
 ### NOTE
 * While Faker generates data at random, returned values are not guaranteed to be unique by default.
-  You must explicity specify when you require unique values, see [details](#ensuring-unique-values).
+  You must explicitly specify when you require unique values, see [details](#ensuring-unique-values).
   Values also can be deterministic if you use the deterministic feature, see [details](#deterministic-random)
 * This is the `master` branch of Faker and may contain changes that are not yet released.
   Please refer the README of your version for the available methods.

data/lib/faker.rb

@@ -151,20 +151,18 @@ module Faker
 
       # Call I18n.translate with our configured locale if no
       # locale is specified
-      def translate(*args)
-        opts = args.last.is_a?(Hash) ? args.pop : {}
+      def translate(*args, **opts)
         opts[:locale] ||= Faker::Config.locale
         opts[:raise] = true
-        I18n.translate(*args.push(opts))
+        I18n.translate(*args, **opts)
       rescue I18n::MissingTranslationData
-        opts = args.last.is_a?(Hash) ? args.pop : {}
         opts[:locale] = :en
 
         # Super-simple fallback -- fallback to en if the
         # translation was missing.  If the translation isn't
         # in en either, then it will raise again.
         disable_enforce_available_locales do
-          I18n.translate(*args.push(opts))
+          I18n.translate(*args, **opts)
         end
       end
 

data/lib/faker/default/address.rb

@@ -5,6 +5,19 @@ module Faker
     flexible :address
 
     class << self
+      ##
+      # Produces the name of a city.
+      #
+      # @param options [Hash]
+      # @option with_state [Boolean] Whether to include the state name in the output.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.city #=> "Imogeneborough"
+      #   Faker::Address.city(options: { with_state: true })
+      #     #=> "Northfort, California"
+      #
+      # @faker.version 0.3.0
       def city(legacy_options = NOT_GIVEN, options: {})
         warn_for_deprecated_arguments do |keywords|
           keywords << :options if legacy_options != NOT_GIVEN
@@ -13,10 +26,29 @@ module Faker
         parse(options[:with_state] ? 'address.city_with_state' : 'address.city')
       end
 
+      ##
+      # Produces a street name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.street_name #=> "Larkin Fork"
+      #
+      # @faker.version 0.3.0
       def street_name
         parse('address.street_name')
       end
 
+      ##
+      # Produces a street address.
+      #
+      # @param include_secondary [Boolean] Whether or not to include the secondary address.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.street_address #=> "282 Kevin Brook"
+      #
+      # @faker.version 0.3.0
       def street_address(legacy_include_secondary = NOT_GIVEN, include_secondary: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :include_secondary if legacy_include_secondary != NOT_GIVEN
@@ -25,18 +57,70 @@ module Faker
         numerify(parse('address.street_address') + (include_secondary ? ' ' + secondary_address : ''))
       end
 
+      ##
+      # Produces a secondary address.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.secondary_address #=> "Apt. 672"
+      #
+      # @faker.version 0.3.0
       def secondary_address
         bothify(fetch('address.secondary_address'))
       end
 
+      ##
+      # Produces a building number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.building_number #=> "7304"
+      #
+      # @faker.version 0.3.0
       def building_number
         bothify(fetch('address.building_number'))
       end
 
+      ##
+      # Produces the name of a community.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.community #=> "University Crossing"
+      #
+      # @faker.version 1.8.0
       def community
         parse('address.community')
       end
 
+      ##
+      #
+      # Produces a mail box number.
+      # @return [String]
+      #
+      # @example
+      # Faker::Address.mail_box #=> "PO Box 123"
+      #
+      # @faker.version 2.9.1
+      def mail_box
+        bothify(fetch('address.mail_box'))
+      end
+
+      ##
+      # Produces a Zip Code.
+      #
+      # @param state_abbreviation [String] an abbreviation for a state where the zip code should be located.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.zip_code #=> "58517"
+      #   Faker::Address.zip_code #=> "23285-4905"
+      #   Faker::Address.zip_code(state_abbreviation: 'CO') #=> "80011"
+      #
+      # @faker.version 0.3.0
       def zip_code(legacy_state_abbreviation = NOT_GIVEN, state_abbreviation: '')
         warn_for_deprecated_arguments do |keywords|
           keywords << :state_abbreviation if legacy_state_abbreviation != NOT_GIVEN
@@ -52,6 +136,15 @@ module Faker
         bothify(fetch('address.postcode_by_state.' + state_abbreviation))
       end
 
+      ##
+      # Produces the name of a time zone.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.time_zone #=> "Asia/Yakutsk"
+      #
+      # @faker.version 1.2.0
       def time_zone
         fetch('address.time_zone')
       end
@@ -59,30 +152,96 @@ module Faker
       alias zip zip_code
       alias postcode zip_code
 
+      ##
+      # Produces a street suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.street_suffix #=> "Street"
+      #
+      # @faker.version 0.3.0
       def street_suffix
         fetch('address.street_suffix')
       end
 
+      ##
+      # Produces a city suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.city_suffix #=> "fort"
+      #
+      # @faker.version 0.3.0
       def city_suffix
         fetch('address.city_suffix')
       end
 
+      ##
+      # Produces a city prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.city_prefix #=> "Lake"
+      #
+      # @faker.version 0.3.0
       def city_prefix
         fetch('address.city_prefix')
       end
 
+      ##
+      # Produces a state abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.state_abbr #=> "AP"
+      #
+      # @faker.version 0.3.0
       def state_abbr
         fetch('address.state_abbr')
       end
 
+      ##
+      # Produces the name of a state.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.state #=> "California"
+      #
+      # @faker.version 0.3.0
       def state
         fetch('address.state')
       end
 
+      ##
+      # Produces the name of a country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country #=> "French Guiana"
+      #
+      # @faker.version 0.3.0
       def country
         fetch('address.country')
       end
 
+      ##
+      # Produces a country by ISO country code. See the
+      # [List of ISO 3166 country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
+      # on Wikipedia for a full list.
+      #
+      # @param code [String] An ISO country code.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_by_code(code: 'NL') #=> "Netherlands"
+      #
+      # @faker.version 1.9.2
       def country_by_code(legacy_code = NOT_GIVEN, code: 'US')
         warn_for_deprecated_arguments do |keywords|
           keywords << :code if legacy_code != NOT_GIVEN
@@ -91,6 +250,16 @@ module Faker
         fetch('address.country_by_code.' + code)
       end
 
+      ##
+      # Produces an ISO 3166 country code when given a country name.
+      #
+      # @param name [String] Country name in snake_case format.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_name_to_code(name: 'united_states') #=> "US"
+      #
+      # @faker.version 1.9.2
       def country_name_to_code(legacy_name = NOT_GIVEN, name: 'united_states')
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
@@ -99,22 +268,68 @@ module Faker
         fetch('address.country_by_name.' + name)
       end
 
+      ##
+      # Produces an ISO 3166 country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_code #=> "IT"
+      #
+      # @faker.version 1.4.0
       def country_code
         fetch('address.country_code')
       end
 
+      ##
+      # Produces a long (alpha-3) ISO 3166 country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_code_long #=> "ITA"
+      #
+      # @faker.version 0.3.0
       def country_code_long
         fetch('address.country_code_long')
       end
 
+      ##
+      # Produces a latitude.
+      #
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Address.latitude #=> -58.17256227443719
+      #
+      # @faker.version 1.0.0
       def latitude
         ((rand * 180) - 90).to_f
       end
 
+      ##
+      # Produces a longitude.
+      #
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Address.longitude #=> -156.65548382095133
+      #
+      # @faker.version 1.0.0
       def longitude
         ((rand * 360) - 180).to_f
       end
 
+      ##
+      # Produces a full address.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.full_address
+      #     #=> "282 Kevin Brook, Imogeneborough, CA 58517"
+      #
+      # @faker.version 0.3.0
       def full_address
         parse('address.full_address')
       end