diff --git a/.gitignore b/.gitignore index 447be08cc7..8dc403f08c 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,6 @@ coverage/* # Ignore rvm and rbenv files .ruby-version .ruby-gemset + +.yardoc/ +doc/ diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000000..8ef2fed38a --- /dev/null +++ b/.yardopts @@ -0,0 +1,5 @@ +--no-private +--tag faker.version:"Available since" +--exclude lib/faker/deprecate/ +--output-dir yard_docs +lib/**/*.rb \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d976f67af..95f9d2c45a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,74 +1,110 @@ -We love pull requests. Here's a quick guide: - -1. Fork the repo. - -2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: `bundle && bundle exec rake` - -3. We are using [Rubocop](https://github.com/bbatsov/rubocop) because we love static code analyzers. - * Ways to run Rubocop: - - `bundle exec rubocop` - - `bundle exec rake` would run the test suite and after that it runs the Ruby static code analyzer. - -4. Please add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need a test! We use [Minitest](https://github.com/seattlerb/minitest) in this project. - -5. Make the test pass. Always use `sample`, `shuffle`, and `rand` from the Base class (just like the rest of the code) rather than `Array#sample`, `Array#shuffle` and `Kernel#rand` to preserve the deterministic feature. - -6. We care about code coverage and use `SimpleCov` to analyze the code and generate test coverage reports. It's possible to check the test coverage by running `open coverage/index.html`. Please make sure to not decrease our `current % covered` and add appropriate test cases when necessary. - -7. When adding a new class, add a new yaml file to `lib/locales/en` rather than adding translations to `lib/locales/en.yml`. For example, if you add Faker::MyThing, put your translations in `lib/locales/en/my_thing.yml`. See [the locale README](./lib/locales/en/README.md) for more info. - -8. When removing a method, don't forget to deprecate it. You can `extend Gem::Deprecate` and use the `deprecate` method to accomplish this task. - -9. Methods with optional arguments should use keyword rather than positional arguments. An exception to this could be a method that takes only one optional argument, and it's unlikely that that method would ever take more than one optional argument. - -10. Push to your fork and submit a pull request. - -### Github Flow for contributors and collaborators - -For those of you with commit access, please check out Scott Chacon's blog post about [github flow](http://scottchacon.com/2011/08/31/github-flow.html) - -> * Anything in the master branch is deployable -> * To work on something new, create a descriptively named branch off of master (ie: new-oauth2-scopes) -> * Commit to that branch locally and regularly push your work to the same named branch on the server -> * When you need feedback or help, or you think the branch is ready for merging, open a pull request -> * After someone else has reviewed and signed off on the feature, you can merge it into master - -If you're reviewing a PR, you should ask yourself: -> * Does it work as described? A PR should have a great description. -> * Is it understandable? -> * Is it well implemented? -> * Is it well tested? -> * Is it well documented? -> * Is it following the structure of the project? - -### Syntax/Good practices: - -* Two spaces, no tabs. -* No trailing whitespace. Blank lines should not have any space. -* Prefer `&&`, `||` over `and`, `or`. -* `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`. -* `a = b` and not `a=b`. -* use dash syntax for yaml arrays: -```Yaml -# this -a_things: - - small_thing - - big_thing - - other_thing - -# instead of these: -b_things: [small_thing, big_thing, other_thing] -c_things: [ - small_thing, - big_thing, - other_thing, -] - -# If in doubt, `bundle exec rake reformat_yaml['lib/path/to/file.yml']` -``` -* In general, follow the conventions you see used in the source already. -* **ALL SHALL OBEY THE RUBOCOP** - -### Tips - -* Use the `rake console` task to start a session with Faker loaded. +We love pull requests. Here's a quick guide: + +1. Fork the repo. + +2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: `bundle && bundle exec rake` + +3. We are using [Rubocop](https://github.com/bbatsov/rubocop) because we love static code analyzers. + * Ways to run Rubocop: + - `bundle exec rubocop` + - `bundle exec rake` would run the test suite and after that it runs the Ruby static code analyzer. + +4. Please add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need a test! We use [Minitest](https://github.com/seattlerb/minitest) in this project. + +5. Make the test pass. Always use `sample`, `shuffle`, and `rand` from the Base class (just like the rest of the code) rather than `Array#sample`, `Array#shuffle` and `Kernel#rand` to preserve the deterministic feature. + +6. We care about code coverage and use `SimpleCov` to analyze the code and generate test coverage reports. It's possible to check the test coverage by running `open coverage/index.html`. Please make sure to not decrease our `current % covered` and add appropriate test cases when necessary. + +7. When adding a new class, add a new yaml file to `lib/locales/en` rather than adding translations to `lib/locales/en.yml`. For example, if you add Faker::MyThing, put your translations in `lib/locales/en/my_thing.yml`. See [the locale README](./lib/locales/en/README.md) for more info. + +8. When removing a method, don't forget to deprecate it. You can `extend Gem::Deprecate` and use the `deprecate` method to accomplish this task. + +9. Methods with optional arguments should use keyword rather than positional arguments. An exception to this could be a method that takes only one optional argument, and it's unlikely that that method would ever take more than one optional argument. + +10. Push to your fork and submit a pull request. + +### Github Flow for contributors and collaborators + +For those of you with commit access, please check out Scott Chacon's blog post about [github flow](http://scottchacon.com/2011/08/31/github-flow.html) + +> * Anything in the master branch is deployable +> * To work on something new, create a descriptively named branch off of master (ie: new-oauth2-scopes) +> * Commit to that branch locally and regularly push your work to the same named branch on the server +> * When you need feedback or help, or you think the branch is ready for merging, open a pull request +> * After someone else has reviewed and signed off on the feature, you can merge it into master + +If you're reviewing a PR, you should ask yourself: +> * Does it work as described? A PR should have a great description. +> * Is it understandable? +> * Is it well implemented? +> * Is it well tested? +> * Is it well documented? +> * Is it following the structure of the project? + +### Syntax/Good practices: + +#### Documentation +Include [YARD] style docs for all methods that includes: +- A short description of what the method generates +- Descriptions for all params (`@param`) +- The return type (`@return`) +- At least one example of the output (`@example`) +- The version that the method was added (`@faker.version`) + - Set as `next` for new methods + +```ruby +## +# Produces a random string of alphabetic characters, (no digits) +# +# @param char_count [Integer] The length of the string to generate +# +# @return [String] +# +# @example +# Faker:Alphanumeric.alpha +# #=> "kgdpxlgwjirlqhwhrebvuomdcjjpeqlq" +# @example +# Faker:Alphanumeric.alpha(number: 10) +# #=> "zlvubkrwga" +# +# @faker.version next +def alpha(number: 32) + # ... +end +``` + +#### Code Styles +Please follow these guidelines when adding new code: +* Two spaces, no tabs. +* No trailing whitespace. Blank lines should not have any space. +* Prefer `&&`, `||` over `and`, `or`. +* `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`. +* `a = b` and not `a=b`. +* In general, follow the conventions you see used in the source already. +* **ALL SHALL OBEY THE RUBOCOP** + +#### YAML +Please use dash syntax for yaml arrays: +```Yaml +# instead of these +b_things: [small_thing, big_thing, other_thing] +c_things: [ + small_thing, + big_thing, + other_thing, +] + +# this is preferred +a_things: + - small_thing + - big_thing + - other_thing +``` +- If in doubt, `bundle exec rake reformat_yaml['lib/path/to/file.yml']` + +### Tips + +* Use the `rake console` task to start a session with Faker loaded. +* Use `bundle exec yard server -r` to launch the YARD Doc server + +[YARD]: (https://www.rubydoc.info/gems/yard/file/README.md) \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 4ececec7c0..64ef6face8 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -43,6 +43,7 @@ GEM power_assert timecop (0.9.1) unicode-display_width (1.6.0) + yard (0.9.18) PLATFORMS ruby @@ -56,6 +57,7 @@ DEPENDENCIES simplecov (= 0.17.0) test-unit (= 3.3.3) timecop (= 0.9.1) + yard BUNDLED WITH 1.17.3 diff --git a/Rakefile b/Rakefile index 6b1f42c9dd..a1e10308e2 100644 --- a/Rakefile +++ b/Rakefile @@ -20,4 +20,7 @@ end require 'rubocop/rake_task' RuboCop::RakeTask.new +require 'yard' +YARD::Rake::YardocTask.new + task default: %w[test rubocop] diff --git a/faker.gemspec b/faker.gemspec index 5ca6df36f1..80461cc34d 100644 --- a/faker.gemspec +++ b/faker.gemspec @@ -24,6 +24,8 @@ Gem::Specification.new do |spec| spec.metadata['changelog_uri'] = 'https://github.com/faker-ruby/faker/blob/master/CHANGELOG.md' spec.metadata['source_code_uri'] = 'https://github.com/faker-ruby/faker' spec.metadata['bug_tracker_uri'] = 'https://github.com/faker-ruby/faker/issues' + spec.metadata['documentation_uri'] = 'https://rubydoc.info/github/faker-ruby/faker/master' + spec.metadata['yard.run'] = 'yri' spec.add_dependency('i18n', '~> 1.6.0') @@ -34,4 +36,5 @@ Gem::Specification.new do |spec| spec.add_development_dependency('simplecov', '0.17.0') spec.add_development_dependency('test-unit', '3.3.3') spec.add_development_dependency('timecop', '0.9.1') + spec.add_development_dependency('yard') end diff --git a/lib/faker/blockchain/bitcoin.rb b/lib/faker/blockchain/bitcoin.rb index f1bd3f5313..248b7fa814 100644 --- a/lib/faker/blockchain/bitcoin.rb +++ b/lib/faker/blockchain/bitcoin.rb @@ -7,21 +7,47 @@ module Faker class Blockchain class Bitcoin < Base class << self + # @private PROTOCOL_VERSIONS = { main: 0, testnet: 111 }.freeze + ## + # Produces a Bitcoin wallet address + # + # @return [String] + # + # @example + # Faker::Blockchain::Bitcoin.address + # #=> "147nDP22h3pHrLt2qykTH4txUwQh1ccaXp" + # + # @faker.version 1.9.2 def address address_for(:main) end + ## + # Produces a Bitcoin testnet address + # + # @return [String] + # + # @example + # Faker::Blockchain::Bitcoin.testnet_address + # #=> "n4YjRyYD6V6zREpk6opqESDqD3KYnMdVEB" + # + # @faker.version 1.9.2 def testnet_address address_for(:testnet) end protected + ## + # Generates a random Bitcoin address for the given network + # + # @param network [Symbol] The name of network protocol to generate an address for + # @return [String] A Bitcoin address def address_for(network) version = PROTOCOL_VERSIONS.fetch(network) packed = version.chr + Faker::Config.random.bytes(20) diff --git a/lib/faker/blockchain/ethereum.rb b/lib/faker/blockchain/ethereum.rb index 5cc9b61341..8d60bd2a97 100644 --- a/lib/faker/blockchain/ethereum.rb +++ b/lib/faker/blockchain/ethereum.rb @@ -4,6 +4,16 @@ module Faker class Blockchain class Ethereum < Base class << self + ## + # Produces a random Ethereum wallet address + # + # @return [String] + # + # @example + # Faker::Blockchain::Ethereum.address + # #=> "0xd392b0c0500700d02d27ab30805ec80ddd3320ff" + # + # @faker.version 1.9.1 def address hex_alphabet = '0123456789abcdef' var = +'0x' diff --git a/lib/faker/blockchain/tezos.rb b/lib/faker/blockchain/tezos.rb index 444e568127..e1ca8315ca 100644 --- a/lib/faker/blockchain/tezos.rb +++ b/lib/faker/blockchain/tezos.rb @@ -7,6 +7,7 @@ module Faker class Blockchain class Tezos < Base class << self + # @private PREFIXES = { tz1: [6, 161, 159], KT1: [2, 90, 121], @@ -17,28 +18,83 @@ class << self o: [5, 116] }.freeze + ## + # Produces a random Tezos account address + # + # @return [String] + # + # @example + # Faker::Blockchain::Tezos.account + # #=> "tz1eUsgK6aj752Fbxwk5sAoEFvSDnPjZ4qvk" + # + # @faker.version 1.9.2 def account encode_tz(:tz1, 20) end + ## + # Produces a random Tezos contract + # + # @return [String] + # + # @example + # Faker::Blockchain::Tezos.contract + # #=> "KT1MroqeP15nnitB4CnNfkqHYa2NErhPPLWF" + # + # @faker.version 1.9.2 def contract encode_tz(:KT1, 20) end + ## + # Produces a random Tezos operation + # + # @return [String] + # + # @example + # Faker::Blockchain::Tezos.operation + # #=> "onygWYXJX3xNstFLv9PcCrhQdCkENC795xwSinmTEc1jsDN4VDa" + # + # @faker.version 1.9.2 def operation encode_tz(:o, 32) end + ## + # Produces a random Tezos block + # + # @return [String] + # + # @example + # Faker::Blockchain::Tezos.block + # #=> "BMbhs2rkY1dvAkAyRytvPsjFQ2RiPrBhYkxvWpY65dzkdSuw58a" + # + # @faker.version 1.9.4 def block encode_tz(:B, 32) end + ## + # Produces a random Tezos signature + # + # @return [String] + # + # @example + # Faker::Blockchain::Tezos.signature + # #=> "edsigu165B7VFf3Dpw2QABVzEtCxJY2gsNBNcE3Ti7rRxtDUjqTFRpg67EdAQmY6YWPE5tKJDMnSTJDFu65gic8uLjbW2YwGvAZ" + # + # @faker.version 1.9.2 def signature encode_tz(:edsig, 64) end protected + ## + # @param prefix [Symbol] + # @param payload_size [Integer] The size of the payload + # + # @return [String] def encode_tz(prefix, payload_size) prefix = PREFIXES.fetch(prefix) packed = prefix.map(&:chr).join('') + Faker::Config.random.bytes(payload_size) diff --git a/lib/faker/books/book.rb b/lib/faker/books/book.rb index d61c1988c8..6da6a02f2e 100644 --- a/lib/faker/books/book.rb +++ b/lib/faker/books/book.rb @@ -5,18 +5,54 @@ class Book < Base flexible :book class << self + ## + # Produces a random book title + # + # @return [String] + # + # @example + # Faker::Book.title #=> "The Odd Sister" + # + # @faker.version 1.9.3 def title fetch('book.title') end + ## + # Produces a random book author + # + # @return [String] + # + # @example + # Faker::Book.author #=> "Alysha Olsen" + # + # @faker.version 1.9.3 def author parse('book.author') end + ## + # Produces a random book publisher + # + # @return [String] + # + # @example + # Faker::Book.publisher #=> "Opus Reader" + # + # @faker.version 1.9.3 def publisher fetch('book.publisher') end + ## + # Produces a random genre + # + # @return [String] + # + # @example + # Faker::Book.genre #=> "Mystery" + # + # @faker.version 1.9.3 def genre fetch('book.genre') end diff --git a/lib/faker/books/culture_series.rb b/lib/faker/books/culture_series.rb index 2976385326..0dd8243fad 100644 --- a/lib/faker/books/culture_series.rb +++ b/lib/faker/books/culture_series.rb @@ -4,27 +4,76 @@ module Faker class Books class CultureSeries < Base flexible :culture_series + class << self + ## + # @return [String] + # + # @example + # Faker::Books::CultureSeries.book + # #=> "The Player of Games" + # + # @faker.version 1.9.3 def book fetch('culture_series.books') end + ## + # @return [String] + # + # @example + # Faker::Books::CultureSeries.culture_ship + # #=> "Fate Amenable To Change" + # + # @faker.version 1.9.3 def culture_ship fetch('culture_series.culture_ships') end + ## + # @return [String] + # + # @example + # Faker::Books::CultureSeries.culture_ship_class + # #=> "General Systems Vehicle" + # + # @faker.version 1.9.3 def culture_ship_class fetch('culture_series.culture_ship_classes') end + ## + # @return [String] + # + # @example + # Faker::Books::CultureSeries.culture_ship_class_abv + # #=> "The Odd Sister" + # + # @faker.version 1.9.3 def culture_ship_class_abv fetch('culture_series.culture_ship_class_abvs') end + ## + # @return [String] + # + # @example + # Faker::Books::CultureSeries.civ + # #=> "Culture" + # + # @faker.version 1.9.3 def civ fetch('culture_series.civs') end + ## + # @return [String] + # + # @example + # Faker::Books::CultureSeries.planet + # #=> "Xinth" + # + # @faker.version 1.9.3 def planet fetch('culture_series.planets') end diff --git a/lib/faker/books/dune.rb b/lib/faker/books/dune.rb index b03adb0d46..699a142336 100644 --- a/lib/faker/books/dune.rb +++ b/lib/faker/books/dune.rb @@ -2,23 +2,62 @@ module Faker class Books + ## + # A Faker module beyond your dreams, test data beyond your imagination. class Dune < Base class << self - # QUOTED_CHARACTERS = fetch("dune.quotes") - # SAYING_SOURCES = %w(translate("faker.dune.sources")) - + ## + # Produces the name of a character from Dune + # + # @return [String] + # + # @example + # Faker::Books::Dune.character #=> "Leto Atreides" + # + # @faker.version 1.9.3 def character fetch('dune.characters') end + ## + # @return [String] + # + # @example + # Faker::Books::Dune.title #=> "Duke" + # + # @faker.version 1.9.3 def title fetch('dune.titles') end + ## + # Produces the name of a planet from Dune + # + # @return [String] + # + # @example + # Faker::Books::Dune.planet #=> "Caladan" + # + # @faker.version 1.9.3 def planet fetch('dune.planets') end + ## + # Produces a quote from Dune + # + # @param character [String] The name of the character that the quote should be from + # + # @return [String] + # + # @example + # Faker::Books::Dune.quote + # #=> "A dead man, surely, no longer requires that water." + # @example + # Faker::Books::Dune.quote(character: "baron_harkonnen") + # #=> "He who controls the spice, controls the universe!" + # + # @faker.version 1.9.3 def quote(legacy_character = NOT_GIVEN, character: nil) warn_for_deprecated_arguments do |keywords| keywords << :character if legacy_character != NOT_GIVEN @@ -40,6 +79,20 @@ def quote(legacy_character = NOT_GIVEN, character: nil) fetch('dune.quotes.' + character) end + ## + # Produces a saying from Dune + # + # @param source [String] + # + # @return [String] + # + # @example + # Faker::Books::Dune.saying #=> "You do not beg the sun for mercy." + # @example + # Faker::Books::Dune.saying(source: "fremen") + # #=> "May thy knife chip and shatter." + # + # @faker.version 1.9.3 def saying(legacy_source = NOT_GIVEN, source: nil) warn_for_deprecated_arguments do |keywords| keywords << :source if legacy_source != NOT_GIVEN diff --git a/lib/faker/books/lovecraft.rb b/lib/faker/books/lovecraft.rb index 70796237ff..f506e1529e 100644 --- a/lib/faker/books/lovecraft.rb +++ b/lib/faker/books/lovecraft.rb @@ -4,10 +4,31 @@ module Faker class Books class Lovecraft < Base class << self + ## + # Produces the name of a location + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.location #=> "Kingsport" + # + # @faker.version 1.9.3 def location fetch('lovecraft.location') end + ## + # @param number [Integer] The number of times to repeat the chant + # @return [String] + # + # @example + # Faker::Books::Lovecraft.fhtagn + # #=> "Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn" + # @example + # Faker::Books::Lovecraft.fhtagn(number: 3) + # #=> "Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fht... + # + # @faker.version 1.9.3 def fhtagn(legacy_number = NOT_GIVEN, number: 1) warn_for_deprecated_arguments do |keywords| keywords << :number if legacy_number != NOT_GIVEN @@ -16,14 +37,51 @@ def fhtagn(legacy_number = NOT_GIVEN, number: 1) Array.new(number) { fetch('lovecraft.fhtagn') }.join('. ') end + ## + # Produces the name of a deity + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.deity #=> "Shub-Niggurath" + # + # @faker.version 1.9.3 def deity fetch('lovecraft.deity') end + ## + # Produces the name of a tome + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.tome #=> "Book of Eibon" + # + # @faker.version 1.9.3 def tome fetch('lovecraft.tome') end + ## + # Produces a random sentence + # + # @param word_count [Integer] The number of words to have in the sentence + # @param random_words_to_add [Integer] + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.sentence + # #=> "Furtive antiquarian squamous dank cat loathsome amorphous lurk." + # @example + # Faker::Books::Lovecraft.sentence(word_count: 3) + # #=> "Daemoniac antediluvian fainted squamous comprehension gambrel nameless singular." + # @example + # Faker::Books::Lovecraft.sentence(word_count: 3, random_words_to_add: 1) + # #=> "Amorphous indescribable tenebrous." + # + # @faker.version 1.9.3 def sentence(legacy_word_count = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, random_words_to_add: 6) warn_for_deprecated_arguments do |keywords| keywords << :word_count if legacy_word_count != NOT_GIVEN @@ -33,11 +91,49 @@ def sentence(legacy_word_count = NOT_GIVEN, legacy_random_words_to_add = NOT_GIV words(number: word_count + rand(random_words_to_add.to_i).to_i, spaces_allowed: true).join(' ').capitalize + '.' end + ## + # Produces a random word + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.word #=> "furtive" + # + # @faker.version 1.9.3 def word random_word = sample(translate('faker.lovecraft.words')) random_word =~ /\s/ ? word : random_word end + ## + # Produces a array of random words + # + # @param number [Integer] Number of words to generate + # @param spaces_allowed [Boolean] If true, generated words can contain spaces + # + # @return [Array] + # + # @example + # Faker::Books::Lovecraft.words + # #=> [ + # # "manuscript", + # # "abnormal", + # # "singular", + # # ] + # @example + # Faker::Books::Lovecraft.words(number: 2) + # #=> [ + # # "daemoniac", + # # "cat", + # # ] + # @example + # Faker::Books::Lovecraft.words(number: 2, spaces_allowed: 1) + # #=> [ + # # "lurk", + # # "charnel", + # # ] + # + # @faker.version 1.9.3 def words(legacy_number = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number: 3, spaces_allowed: false) warn_for_deprecated_arguments do |keywords| keywords << :number if legacy_number != NOT_GIVEN @@ -54,6 +150,28 @@ def words(legacy_number = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number: words.each_with_index { |w, i| words[i] = word if w =~ /\s/ } end + ## + # Produces a array of random sentences + # + # @param number [Integer] Number of sentences to generate + # + # @return [Array] + # + # @example + # Faker::Books::Lovecraft.sentences + # #=> [ + # # "Nameless loathsome decadent gambrel.", + # # "Ululate swarthy immemorial cat madness gibbous unmentionable unnamable.", + # # "Decadent antediluvian non-euclidean tentacles amorphous tenebrous.", + # # ] + # @example + # Faker::Books::Lovecraft.sentences(number: 2) + # #=> [ + # # "Antediluvian amorphous unmentionable singular accursed squamous immemorial.", + # # "Gambrel daemoniac gibbous stygian shunned ululate iridescence abnormal.", + # # ] + # + # @faker.version 1.9.3 def sentences(legacy_number = NOT_GIVEN, number: 3) warn_for_deprecated_arguments do |keywords| keywords << :number if legacy_number != NOT_GIVEN @@ -66,6 +184,25 @@ def sentences(legacy_number = NOT_GIVEN, number: 3) end end + ## + # Produces a random paragraph + # + # @param sentence_count [Integer] Number of sentences to generate + # @param random_sentences_to_add [Integer] + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.paragraph + # #=> "Squamous nameless daemoniac fungus ululate. Cyclopean stygian decadent loathsome manuscript tenebrous. Foetid abnormal stench. Dank non-euclidean comprehension eldritch. Charnel singular shunned lurk effulgence fungus." + # @example + # Faker::Books::Lovecraft.paragraph(sentence_count: 2) + # #=> "Decadent lurk tenebrous loathsome furtive spectral amorphous gibbous. Gambrel eldritch daemoniac cat madness comprehension stygian effulgence." + # @example + # Faker::Books::Lovecraft.paragraph(sentence_count: 1, random_sentences_to_add: 1) + # #=> "Stench cyclopean fainted antiquarian nameless. Antiquarian ululate tenebrous non-euclidean effulgence." + # + # @faker.version 1.9.3 def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_random_sentences_to_add = NOT_GIVEN, sentence_count: 3, random_sentences_to_add: 3) warn_for_deprecated_arguments do |keywords| keywords << :sentence_count if legacy_sentence_count != NOT_GIVEN @@ -75,6 +212,28 @@ def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_random_sentences_to_add sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i).join(' ') end + ## + # Produces a array of random paragraphs + # + # @param number [Integer] Number of paragraphs to generate + # + # @return [Array] + # + # @example + # Faker::Books::Lovecraft.paragraphs + # #=> [ + # # "Noisome daemoniac gibbous abnormal antediluvian. Unutterable fung... + # # "Non-euclidean immemorial indescribable accursed furtive. Dank unn... + # # "Charnel antediluvian unnamable cat blasphemous comprehension tene... + # # ] + # @example + # Faker::Books::Lovecraft.paragraphs(number: 2) + # #=> [ + # # "Hideous amorphous manuscript antediluvian non-euclidean cat eldri... + # # "Tenebrous unnamable comprehension antediluvian lurk. Lurk spectra... + # # ] + # + # @faker.version 1.9.3 def paragraphs(legacy_number = NOT_GIVEN, number: 3) warn_for_deprecated_arguments do |keywords| keywords << :number if legacy_number != NOT_GIVEN @@ -87,6 +246,19 @@ def paragraphs(legacy_number = NOT_GIVEN, number: 3) end end + ## + # @param characters [Integer] Number of characters to generate in the paragraph + # + # @return [String] + # + # @example + # Faker::Books::Lovecraft.paragraph_by_chars + # #=> "Truffaut stumptown trust fund 8-bit messenger bag portland. Meh kombucha selvage swag biodiesel. Lomo kinfolk jean shorts asymmetrical diy. Wayfarers portland twee stumptown. Wes anderson biodiesel retro 90's pabst. Diy echo 90's mixtape semiotics. Cornho." + # @example + # Faker::Books::Lovecraft.paragraph_by_chars(characters: 128) + # #=> "Effulgence madness noisome. Fungus stygian mortal madness amorphous dank. Decadent noisome hideous effulgence. Tentacles charne." + # + # @faker.version 1.9.3 def paragraph_by_chars(legacy_characters = NOT_GIVEN, characters: 256) warn_for_deprecated_arguments do |keywords| keywords << :characters if legacy_characters != NOT_GIVEN diff --git a/lib/faker/creature/animal.rb b/lib/faker/creature/animal.rb index a1e4280483..dbb3b6b133 100644 --- a/lib/faker/creature/animal.rb +++ b/lib/faker/creature/animal.rb @@ -4,6 +4,15 @@ module Faker class Creature class Animal < Base class << self + ## + # Produces a random animal name + # + # @return [String] + # + # @example + # Faker::Creature::Animal.name #=> "fly" + # + # @faker.version 1.9.2 def name fetch('creature.animal.name') end diff --git a/lib/faker/creature/cat.rb b/lib/faker/creature/cat.rb index ac089d8a2b..fb0e825569 100644 --- a/lib/faker/creature/cat.rb +++ b/lib/faker/creature/cat.rb @@ -6,14 +6,41 @@ class Cat < Base flexible :cat class << self + ## + # Produces a random name for a cat + # + # @return [String] + # + # @example + # Faker::Creature::Cat.name #=> "Felix" + # + # @faker.version 1.9.2 def name fetch('creature.cat.name') end + ## + # Produces a random cat breed + # + # @return [String] + # + # @example + # Faker::Creature::Cat.breed #=> "Scottish Fold" + # + # @faker.version 1.9.2 def breed fetch('creature.cat.breed') end + ## + # Produces a random cat breed registry + # + # @return [String] + # + # @example + # Faker::Creature::Cat.registry #=> "Fancy Southern Africa Cat Council" + # + # @faker.version 1.9.2 def registry fetch('creature.cat.registry') end diff --git a/lib/faker/creature/dog.rb b/lib/faker/creature/dog.rb index ad7a949544..301defe158 100644 --- a/lib/faker/creature/dog.rb +++ b/lib/faker/creature/dog.rb @@ -6,34 +6,106 @@ class Dog < Base flexible :dog class << self + ## + # Produces a random name for a dog + # + # @return [String] + # + # @example + # Faker::Creature::Dog.name #=> "Spike" + # + # @faker.version 1.9.2 def name fetch('creature.dog.name') end + ## + # Produces a random dog breed + # + # @return [String] + # + # @example + # Faker::Creature::Dog.breed #=> "Yorkshire Terrier" + # + # @faker.version 1.9.2 def breed fetch('creature.dog.breed') end + ## + # Produces a random sound made by a dog + # + # @return [String] + # + # @example + # Faker::Creature::Dog.sound #=> "woof woof" + # + # @faker.version 1.9.2 def sound fetch('creature.dog.sound') end + ## + # Produces a random dog meme phrase + # + # @return [String] + # + # @example + # Faker::Creature::Dog.meme_phrase #=> "smol pupperino" + # + # @faker.version 1.9.2 def meme_phrase fetch('creature.dog.meme_phrase') end + ## + # Produces a random dog age + # + # @return [String] + # + # @example + # Faker::Creature::Dog.age #=> "puppy" + # + # @faker.version 1.9.2 def age fetch('creature.dog.age') end + ## + # Produces a random gender + # + # @return [String] + # + # @example + # Faker::Creature::Dog.gender #=> "Female" + # + # @faker.version 1.9.2 def gender Faker::Gender.binary_type end + ## + # Produces a random coat length + # + # @return [String] + # + # @example + # Faker::Creature::Dog.coat_length #=> "short" + # + # @faker.version 1.9.2 def coat_length fetch('creature.dog.coat_length') end + ## + # Produces a random size of a dog + # + # @return [String] + # + # @example + # Faker::Creature::Dog.size #=> "small" + # + # @faker.version 1.9.2 def size fetch('creature.dog.size') end diff --git a/lib/faker/creature/horse.rb b/lib/faker/creature/horse.rb index 2743e8cc18..72e76f579c 100644 --- a/lib/faker/creature/horse.rb +++ b/lib/faker/creature/horse.rb @@ -6,10 +6,28 @@ class Horse < Base flexible :horse class << self + ## + # Produces a random name for a horse + # + # @return [String] + # + # @example + # Faker::Creature::Horse.name #=> "Noir" + # + # @faker.version 1.9.2 def name fetch('creature.horse.name') end + ## + # Produces a random horse breed + # + # @return [String] + # + # @example + # Faker::Creature::Horse.breed #=> "Spanish Barb see Barb Horse" + # + # @faker.version 1.9.2 def breed fetch('creature.horse.breed') end diff --git a/lib/faker/default/alphanumeric.rb b/lib/faker/default/alphanumeric.rb index 56aeea140c..a0bda47b0f 100644 --- a/lib/faker/default/alphanumeric.rb +++ b/lib/faker/default/alphanumeric.rb @@ -2,9 +2,23 @@ module Faker class Alphanumeric < Base + ## + # List of characters allowed for alphanumeric strings + # @private ALPHANUMS = LLetters + Numbers class << self + ## + # Produces a random string of alphabetic characters (no digits) + # + # @param number [Integer] The length of the string to generate + # + # @return [String] + # + # @example + # Faker::Alphanumeric.alpha(number: 10) #=> "zlvubkrwga" + # + # @faker.version 1.9.2 def alpha(legacy_number = NOT_GIVEN, number: 32) warn_for_deprecated_arguments do |keywords| keywords << :number if legacy_number != NOT_GIVEN @@ -18,15 +32,18 @@ def alpha(legacy_number = NOT_GIVEN, number: 32) ## # Produces a random string of alphanumeric characters # - # @param [Integer] number - # @param [Integer] min_alpha - # @param [Integer] min_numeric + # @param number [Integer] The number of characters to generate + # @param min_alpha [Integer] The minimum number of alphabetic to add to the string + # @param min_numeric [Integer] The minimum number of numbers to add to the string # # @return [String] # - # @example Faker::Alphanumeric.alphanumeric(number: 10) #=> "3yfq2phxtb" - # @example Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3) #=> "3yfq2phxtb" - # @example Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3, min_numeric: 3) #=> "3yfq2phx8b" + # @example + # Faker::Alphanumeric.alphanumeric(number: 10) #=> "3yfq2phxtb" + # @example + # Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3) #=> "3yfq2phxtb" + # @example + # Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3, min_numeric: 3) #=> "3yfq2phx8b" # # @faker.version 2.1.3 def alphanumeric(legacy_number = NOT_GIVEN, number: 32, min_alpha: 0, min_numeric: 0) diff --git a/lib/faker/default/app.rb b/lib/faker/default/app.rb index f5d30505ac..6cf3baf947 100644 --- a/lib/faker/default/app.rb +++ b/lib/faker/default/app.rb @@ -3,18 +3,63 @@ module Faker class App < Base class << self + ## + # Produces an app name. + # + # @return [String] + # + # @example + # Faker::App.name #=> "Treeflex" + # + # @faker.version 1.4.3 def name fetch('app.name') end + ## + # Produces a version string. + # + # @return [String] + # + # @example + # Faker::App.version #=> "1.85" + # + # @faker.version 1.4.3 def version parse('app.version') end + ## + # Produces the name of an app's author. + # + # @return [String] + # + # @example + # Faker::App.author #=> "Daphne Swift" + # + # @faker.version 1.4.3 def author parse('app.author') end + ## + # Produces a String representing a semantic version identifier. + # + # @param major [Integer, Range] An integer to use or a range to pick the integer from. + # @param minor [Integer, Range] An integer to use or a range to pick the integer from. + # @param patch [Integer, Range] An integer to use or a range to pick the integer from. + # @return [String] + # + # @example + # Faker::App.semantic_version #=> "3.2.5" + # @example + # Faker::App.semantic_version(major: 42) #=> "42.5.2" + # @example + # Faker::App.semantic_version(minor: 100..101) #=> "42.100.4" + # @example + # Faker::App.semantic_version(patch: 5..6) #=> "7.2.6" + # + # @faker.version 1.4.3 # rubocop:disable Metrics/ParameterLists def semantic_version(legacy_major = NOT_GIVEN, legacy_minor = NOT_GIVEN, legacy_patch = NOT_GIVEN, major: 0..9, minor: 0..9, patch: 1..9) # rubocop:enable Metrics/ParameterLists diff --git a/lib/faker/default/artist.rb b/lib/faker/default/artist.rb index 3c92439d7b..db960ca879 100644 --- a/lib/faker/default/artist.rb +++ b/lib/faker/default/artist.rb @@ -3,6 +3,15 @@ module Faker class Artist < Base class << self + ## + # Produces the name of an artist. + # + # @return [String] + # + # @example + # Faker::Artist.name #=> "Michelangelo" + # + # @faker.version 1.8.8 def name fetch('artist.names') end diff --git a/lib/faker/default/avatar.rb b/lib/faker/default/avatar.rb index e934f4d683..1699e5a802 100644 --- a/lib/faker/default/avatar.rb +++ b/lib/faker/default/avatar.rb @@ -3,8 +3,39 @@ module Faker class Avatar < Base class << self + # @private SUPPORTED_FORMATS = %w[png jpg bmp].freeze + ## + # Produces a URL for an avatar from robohash.org + # + # @param slug [String, nil] + # @param size [String] image size in pixels, in the format of 'AxB' + # @param format [String] The image file format + # @param set [String] The avatar set to use + # @param bgset [String, nil] The background set to use + # @return [String] A robohash.org URL + # + # @example + # Faker::Avatar.image + # #=> "https://robohash.org/sitsequiquia.png?size=300x300&set=set1" + # @example + # Faker::Avatar.image(slug: "my-own-slug") + # #=> "https://robohash.org/my-own-slug.png?size=300x300&set=set1" + # @example + # Faker::Avatar.image(slug: "my-own-slug", size: "50x50") + # #=> "https://robohash.org/my-own-slug.png?size=50x50&set=set1" + # @example + # Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "jpg") + # #=> "https://robohash.org/my-own-slug.jpg?size=50x50&set=set1" + # @example + # Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "bmp") + # #=> "https://robohash.org/my-own-slug.bmp?size=50x50&set=set1" + # @example + # Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "bmp", set: "set1", bgset: "bg1") + # #=> "https://robohash.org/my-own-slug.bmp?size=50x50&set=set1&bgset=bg1" + # + # @faker.version 1.4.3 # rubocop:disable Metrics/ParameterLists def image(legacy_slug = NOT_GIVEN, legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_set = NOT_GIVEN, legacy_bgset = NOT_GIVEN, slug: nil, size: '300x300', format: 'png', set: 'set1', bgset: nil) # rubocop:enable Metrics/ParameterLists diff --git a/lib/faker/default/boolean.rb b/lib/faker/default/boolean.rb index da7539849a..0cd34684b0 100644 --- a/lib/faker/default/boolean.rb +++ b/lib/faker/default/boolean.rb @@ -3,11 +3,22 @@ module Faker class Boolean < Base class << self + ## + # Produces a boolean + # + # @param true_ratio [Float] The likelihood (as a float, out of 1.0) for the method to return `true`. + # @return [Boolean] + # + # @example + # Faker::Boolean.boolean #=> true + # @example + # Faker::Boolean.boolean(true_ratio: 0.2) #=> false + # + # @faker.version 1.6.2 def boolean(legacy_true_ratio = NOT_GIVEN, true_ratio: 0.5) warn_for_deprecated_arguments do |keywords| keywords << :true_ratio if legacy_true_ratio != NOT_GIVEN end - (rand < true_ratio) end end diff --git a/lib/faker/default/gender.rb b/lib/faker/default/gender.rb index 961c27ca73..7606b56922 100644 --- a/lib/faker/default/gender.rb +++ b/lib/faker/default/gender.rb @@ -3,10 +3,28 @@ module Faker class Gender < Base class << self + ## + # Produces the name of a gender identity. + # + # @return [String] + # + # @example + # Faker::Gender.type #=> "Non-binary" + # + # @faker.version 1.9.0 def type fetch('gender.types') end + ## + # Produces either 'Male' or 'Female'. + # + # @return [String] + # + # @example + # Faker::Gender.binary_type #=> "Female" + # + # @faker.version 1.9.0 def binary_type fetch('gender.binary_types') end diff --git a/lib/faker/default/hacker.rb b/lib/faker/default/hacker.rb index 0fdf34d03d..c4c37f6659 100644 --- a/lib/faker/default/hacker.rb +++ b/lib/faker/default/hacker.rb @@ -1,35 +1,93 @@ # frozen_string_literal: true -# Port of http://shinytoylabs.com/jargon/ module Faker + # Port of http://shinytoylabs.com/jargon/ + # Are you having trouble writing tech-savvy dialogue for your latest screenplay? + # Worry not! Hollywood-grade technical talk is ready to fill out any form where you need to look smart. class Hacker < Base flexible :hacker class << self + ## + # Produces something smart. + # + # @return [String] + # + # @example + # Faker::Hacker.say_something_smart + # #=> "Try to compress the SQL interface, maybe it will program the back-end hard drive!" + # + # @faker.version 1.4.0 def say_something_smart sample(phrases) end + ## + # Short technical abbreviations. + # + # @return [String] + # + # @example + # Faker::Hacker.abbreviation #=> "RAM" + # + # @faker.version 1.4.0 def abbreviation fetch('hacker.abbreviation') end + ## + # Hacker-centric adjectives. + # + # @return [String] + # + # @example + # Faker::Hacker.adjective #=> "open-source" + # + # @faker.version 1.4.0 def adjective fetch('hacker.adjective') end + ## + # Only the best hacker-related nouns. + # + # @return [String] + # + # @example + # Faker::Hacker.noun #=> "bandwidth" + # + # @faker.version 1.4.0 def noun fetch('hacker.noun') end + ## + # Actions that hackers take. + # + # @return [String] + # + # @example + # Faker::Hacker.verb #=> "bypass" + # + # @faker.version 1.4.0 def verb fetch('hacker.verb') end + ## + # Produces a verb that ends with '-ing'. + # + # @return [String] + # + # @example + # Faker::Hacker.ingverb #=> "synthesizing" + # + # @faker.version 1.4.0 def ingverb fetch('hacker.ingverb') end + # @private def phrases ["If we #{verb} the #{noun}, we can get to the #{abbreviation} #{noun} through the #{adjective} #{abbreviation} #{noun}!", "We need to #{verb} the #{adjective} #{abbreviation} #{noun}!", diff --git a/lib/faker/default/house.rb b/lib/faker/default/house.rb index ceb0e754ed..4e8118f688 100644 --- a/lib/faker/default/house.rb +++ b/lib/faker/default/house.rb @@ -3,10 +3,28 @@ module Faker class House < Base class << self + ## + # Produces the name of a piece of furniture. + # + # @return [String] + # + # @example + # Faker::House.furniture #=> "chair" + # + # @faker.version 1.9.2 def furniture fetch('house.furniture') end + ## + # Produces the name of a room in a house. + # + # @return [String] + # + # @example + # Faker::House.room #=> "kitchen" + # + # @faker.version 1.9.2 def room fetch('house.rooms') end diff --git a/lib/faker/default/internet.rb b/lib/faker/default/internet.rb index 176b12d293..8ac771e9fa 100644 --- a/lib/faker/default/internet.rb +++ b/lib/faker/default/internet.rb @@ -74,20 +74,25 @@ def username(legacy_specifier = NOT_GIVEN, legacy_separators = NOT_GIVEN, specif end ## - # Produces a randomized string of characters + # Produces a randomized string of characters suitable for passwords # - # @param [Integer] min_length - # @param [Integer] max_length - # @param [Boolean] mix_case - # @param [Boolean] special_characters + # @param min_length [Integer] The minimum length of the password + # @param max_length [Integer] The maximum length of the password + # @param mix_case [Boolean] Toggles if uppercased letters are allowed. If true, at least one will be added. + # @param special_characters [Boolean] Toggles if special characters are allowed. If true, at least one will be added. # # @return [String] # - # @example Faker::Internet.password #=> "Vg5mSvY1UeRg7" - # @example Faker::Internet.password(min_length: 8) #=> "YfGjIk0hGzDqS0" - # @example Faker::Internet.password(min_length: 10, max_length: 20) #=> "EoC9ShWd1hWq4vBgFw" - # @example Faker::Internet.password(min_length: 10, max_length: 20, mix_case: true) #=> "3k5qS15aNmG" - # @example Faker::Internet.password(min_length: 10, max_length: 20, mix_case: true, special_characters: true) #=> "*%NkOnJsH4" + # @example + # Faker::Internet.password #=> "Vg5mSvY1UeRg7" + # @example + # Faker::Internet.password(min_length: 8) #=> "YfGjIk0hGzDqS0" + # @example + # Faker::Internet.password(min_length: 10, max_length: 20) #=> "EoC9ShWd1hWq4vBgFw" + # @example + # Faker::Internet.password(min_length: 10, max_length: 20, mix_case: true) #=> "3k5qS15aNmG" + # @example + # Faker::Internet.password(min_length: 10, max_length: 20, mix_case: true, special_characters: true) #=> "*%NkOnJsH4" # # @faker.version 2.1.3 # rubocop:disable Metrics/ParameterLists diff --git a/lib/faker/default/lorem.rb b/lib/faker/default/lorem.rb index d8c184fc4d..31bd25069f 100644 --- a/lib/faker/default/lorem.rb +++ b/lib/faker/default/lorem.rb @@ -30,16 +30,17 @@ def character ## # Produces a random string of alphanumeric characters # - # @param [Integer] number - # @param [Integer] min_alpha - # @param [Integer] min_numeric + # @param number [Integer] The number of characters to generate + # @param min_alpha [Integer] The minimum number of alphabetic to add to the string + # @param min_numeric [Integer] The minimum number of numbers to add to the string # # @return [String] # - # @example Faker::Lorem.characters #=> "uw1ep04lhs0c4d931n1jmrspprf5wrj85fefue0y7y6m56b6omquh7br7dhqijwlawejpl765nb1716idmp3xnfo85v349pzy2o9rir23y2qhflwr71c1585fnynguiphkjm8p0vktwitcsm16lny7jzp9t4drwav3qmhz4yjq4k04x14gl6p148hulyqioo72tf8nwrxxcclfypz2lc58lsibgfe5w5p0xv95peafjjmm2frkhdc6duoky0aha" - # @example Faker::Lorem.characters(number: 10) #=> "ang9cbhoa8" - # @example Faker::Lorem.characters(number: 10, min_alpha: 4) #=> "ang9cbhoa8" - # @example Faker::Lorem.characters(number: 10, min_alpha: 4, min_numeric: 1) #=> "ang9cbhoa8" + # @example + # Faker::Lorem.characters #=> "uw1ep04lhs0c4d931n1jmrspprf5w..." + # Faker::Lorem.characters(number: 10) #=> "ang9cbhoa8" + # Faker::Lorem.characters(number: 10, min_alpha: 4) #=> "ang9cbhoa8" + # Faker::Lorem.characters(number: 10, min_alpha: 4, min_numeric: 1) #=> "ang9cbhoa8" # # @faker.version 2.1.3 def characters(legacy_number = NOT_GIVEN, number: 255, min_alpha: 0, min_numeric: 0) diff --git a/lib/faker/default/programming_language.rb b/lib/faker/default/programming_language.rb index 2b503d6ac3..770d403d37 100644 --- a/lib/faker/default/programming_language.rb +++ b/lib/faker/default/programming_language.rb @@ -3,10 +3,28 @@ module Faker class ProgrammingLanguage < Base class << self + ## + # Produces the name of a programming language. + # + # @return [String] + # + # @example + # Faker::ProgrammingLanguage.name #=> "Ruby" + # + # @faker.version 1.8.5 def name fetch('programming_language.name') end + ## + # Produces the name of a programming language's creator. + # + # @return [String] + # + # @example + # Faker::ProgrammingLanguage.creator #=> "Yukihiro Matsumoto" + # + # @faker.version 1.8.5 def creator fetch('programming_language.creator') end diff --git a/lib/faker/default/source.rb b/lib/faker/default/source.rb index bd59e1f7aa..c0cccf900d 100644 --- a/lib/faker/default/source.rb +++ b/lib/faker/default/source.rb @@ -3,6 +3,20 @@ module Faker class Source < Base class << self + ## + # Produces source code for Hello World in a given language. + # + # @param lang [Symbol] The programming language to use + # @return [String] + # + # @example + # Faker::Source.hello_world #=> "puts 'Hello World!'" + # + # @example + # Faker::Source.hello_world(lang: :javascript) + # #=> "alert('Hello World!');" + # + # @faker.version 1.9.0 def hello_world(legacy_lang = NOT_GIVEN, lang: :ruby) warn_for_deprecated_arguments do |keywords| keywords << :lang if legacy_lang != NOT_GIVEN @@ -11,6 +25,20 @@ def hello_world(legacy_lang = NOT_GIVEN, lang: :ruby) fetch("source.hello_world.#{lang}") end + ## + # Produces source code for printing a string in a given language. + # + # @param str [String] The string to print + # @param lang [Symbol] The programming language to use + # @return [String] + # + # @example + # Faker::Source.print #=> "puts 'faker_string_to_print'" + # @example + # Faker::Source.print(str: 'foo bar', lang: :javascript) + # #=> "console.log('foo bar');" + # + # @faker.version 1.9.0 def print(legacy_str = NOT_GIVEN, legacy_lang = NOT_GIVEN, str: 'some string', lang: :ruby) warn_for_deprecated_arguments do |keywords| keywords << :str if legacy_str != NOT_GIVEN @@ -18,16 +46,29 @@ def print(legacy_str = NOT_GIVEN, legacy_lang = NOT_GIVEN, str: 'some string', l warn_for_deprecated_arguments do |keywords| keywords << :lang if legacy_lang != NOT_GIVEN end - code = fetch("source.print.#{lang}") code.gsub('faker_string_to_print', str) end + ## + # Produces source code for printing 1 through 10 in a given language. + # + # @param lang [Symbol] The programming language to use + # @return [String] + # + # @example + # Faker::Source.print_1_to_10 #=> "(1..10).each { |i| puts i }" + # @example + # Faker::Source.print_1_to_10(lang: :javascript) + # # => "for (let i=0; i<10; i++) { + # # console.log(i); + # # }" + # + # @faker.version 1.9.0 def print_1_to_10(legacy_lang = NOT_GIVEN, lang: :ruby) warn_for_deprecated_arguments do |keywords| keywords << :lang if legacy_lang != NOT_GIVEN end - fetch("source.print_1_to_10.#{lang}") end end diff --git a/lib/faker/games/elder_scrolls.rb b/lib/faker/games/elder_scrolls.rb index 732e92db3a..428b803e44 100644 --- a/lib/faker/games/elder_scrolls.rb +++ b/lib/faker/games/elder_scrolls.rb @@ -4,34 +4,106 @@ module Faker class Games class ElderScrolls < Base class << self + ## + # Produces the name of a race from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.race #=> "Argonian" + # + # @faker.version 1.9.2 def race fetch('games.elder_scrolls.race') end + ## + # Produces the name of a city from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.city #=> "Whiterun" + # + # @faker.version 1.9.2 def city fetch('games.elder_scrolls.city') end + ## + # Produces the name of a creature from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.creature #=> "Frost Troll" + # + # @faker.version 1.9.2 def creature fetch('games.elder_scrolls.creature') end + ## + # Produces the name of a region from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.region #=> "Cyrodiil" + # + # @faker.version 1.9.2 def region fetch('games.elder_scrolls.region') end + ## + # Produces the name of a dragon from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.dragon #=> "Blood Dragon" + # + # @faker.version 1.9.2 def dragon fetch('games.elder_scrolls.dragon') end + ## + # Produces a randomly generated name from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.name #=> "Balgruuf The Old" + # + # @faker.version 1.9.2 def name "#{fetch('games.elder_scrolls.first_name')} #{fetch('games.elder_scrolls.last_name')}" end + ## + # Produces a first name from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.first_name #=> "Balgruuf" + # + # @faker.version 1.9.2 def first_name fetch('games.elder_scrolls.first_name') end + ## + # Produces a last name from the Elder Scrolls universe. + # + # @return [String] + # + # @example + # Faker::Games::ElderScrolls.last_name #=> "The Old" + # + # @faker.version 1.9.2 def last_name fetch('games.elder_scrolls.last_name') end diff --git a/lib/faker/games/fallout.rb b/lib/faker/games/fallout.rb index 480b1aa072..b92f539187 100644 --- a/lib/faker/games/fallout.rb +++ b/lib/faker/games/fallout.rb @@ -4,18 +4,55 @@ module Faker class Games class Fallout < Base class << self + ## + # Produces the name of a character from the Fallout games. + # + # @return [String] + # + # @example + # Faker::Games::Fallout.character #=> "Liberty Prime" + # + # @faker.version 1.9.2 def character fetch('games.fallout.characters') end + ## + # Produces the name of a faction from the Fallout games. + # + # @return [String] + # + # @example + # Faker::Games::Fallout.faction #=> "Brotherhood of Steel" + # + # @faker.version 1.9.2 def faction fetch('games.fallout.factions') end + ## + # Produces the name of a location from the Fallout games. + # + # @return [String] + # + # @example + # Faker::Games::Fallout.location #=> "New Vegas" + # + # @faker.version 1.9.2 def location fetch('games.fallout.locations') end + ## + # Produces a quote from the Fallout games. + # + # @return [String] + # + # @example + # Faker::Games::Fallout.quote + # #=> "Democracy is non-negotiable" + # + # @faker.version 1.9.2 def quote fetch('games.fallout.quotes') end diff --git a/lib/faker/games/game.rb b/lib/faker/games/game.rb index 12cd9c1e0d..a5fea5b16a 100644 --- a/lib/faker/games/game.rb +++ b/lib/faker/games/game.rb @@ -5,14 +5,41 @@ class Game < Base flexible :game class << self + ## + # Produces the name of a video game. + # + # @return [String] + # + # @example + # Faker::Game.title #=> "Half-Life 2" + # + # @faker.version 1.9.4 def title fetch('game.title') end + ## + # Produces the name of a video game genre. + # + # @return [String] + # + # @example + # Faker::Game.genre #=> "Real-time strategy" + # + # @faker.version 1.9.4 def genre fetch('game.genre') end + ## + # Produces the name of a video game console or platform. + # + # @return [String] + # + # @example + # Faker::Game.platform #=> "Nintendo Switch" + # + # @faker.version 1.9.4 def platform fetch('game.platform') end diff --git a/lib/faker/games/half_life.rb b/lib/faker/games/half_life.rb index 789fa85afe..0a8c7566f4 100644 --- a/lib/faker/games/half_life.rb +++ b/lib/faker/games/half_life.rb @@ -4,14 +4,41 @@ module Faker class Games class HalfLife < Base class << self + ## + # Produces the name of a character from the Half-Life games. + # + # @return [String] + # + # @example + # Faker::Games::HalfLife.character #=> "Gordon Freeman" + # + # @faker.version 1.9.2 def character fetch('games.half_life.character') end + ## + # Produces the name of an enemy from the Half-Life games. + # + # @return [String] + # + # @example + # Faker::Games::HalfLife.enemy #=> "Headcrab" + # + # @faker.version 1.9.2 def enemy fetch('games.half_life.enemy') end + ## + # Produces the name of a location from the Half-Life games. + # + # @return [String] + # + # @example + # Faker::Games::HalfLife.location #=> "Black Mesa Research Facility" + # + # @faker.version 1.9.2 def location fetch('games.half_life.location') end diff --git a/lib/faker/games/overwatch.rb b/lib/faker/games/overwatch.rb index 0b425d88f6..34087991c1 100644 --- a/lib/faker/games/overwatch.rb +++ b/lib/faker/games/overwatch.rb @@ -4,14 +4,41 @@ module Faker class Games class Overwatch < Base class << self + ## + # Produces the name of a hero from Overwatch. + # + # @return [String] + # + # @example + # Faker::Games::Overwatch.hero #=> "Tracer" + # + # @faker.version 1.8.0 def hero fetch('games.overwatch.heroes') end + ## + # Produces the name of a location from Overwatch. + # + # @return [String] + # + # @example + # Faker::Games::Overwatch.location #=> "Numbani" + # + # @faker.version 1.8.0 def location fetch('games.overwatch.locations') end + ## + # Produces a quote from Overwatch. + # + # @return [String] + # + # @example + # Faker::Games::Overwatch.quote #=> "It's high noon" + # + # @faker.version 1.8.0 def quote fetch('games.overwatch.quotes') end diff --git a/lib/faker/games/super_smash_bros.rb b/lib/faker/games/super_smash_bros.rb index 46211ba320..b845e1f93b 100644 --- a/lib/faker/games/super_smash_bros.rb +++ b/lib/faker/games/super_smash_bros.rb @@ -4,10 +4,28 @@ module Faker class Games class SuperSmashBros < Base class << self + ## + # Produces the name of a fighter from the Smash Bros games. + # + # @return [String] + # + # @example + # Faker::Games::SuperSmashBros.fighter #=> "Mario" + # + # @faker.version 1.9.2 def fighter fetch('games.super_smash_bros.fighter') end + ## + # Produces the name of a stage from the Smash Bros games. + # + # @return [String] + # + # @example + # Faker::Games::SuperSmashBros.stage #=> "Final Destination" + # + # @faker.version 1.9.2 def stage fetch('games.super_smash_bros.stage') end diff --git a/lib/faker/games/zelda.rb b/lib/faker/games/zelda.rb index 7f6ca3cacb..28795f5057 100644 --- a/lib/faker/games/zelda.rb +++ b/lib/faker/games/zelda.rb @@ -5,18 +5,54 @@ class Games class Zelda < Base flexible :space class << self + ## + # Produces the name of a Legend of Zelda game. + # + # @return [String] + # + # @example + # Faker::Games::Zelda.game #=> "Breath of the Wild" + # + # @faker.version 1.7.3 def game fetch('games.zelda.games') end + ## + # Produces the name of a character from the Legend of Zelda games. + # + # @return [String] + # + # @example + # Faker::Games::Zelda.character #=> "Link" + # + # @faker.version 1.7.3 def character fetch('games.zelda.characters') end + ## + # Produces the name of a character from the Legend of Zelda games. + # + # @return [String] + # + # @example + # Faker::Games::Zelda.location #=> "Hyrule Castle" + # + # @faker.version 1.7.3 def location fetch('games.zelda.locations') end + ## + # Produces the name of an item from the Legend of Zelda games. + # + # @return [String] + # + # @example + # Faker::Games::Zelda.item #=> "Boomerang" + # + # @faker.version 1.7.3 def item fetch('games.zelda.items') end diff --git a/lib/faker/tv_shows/breaking_bad.rb b/lib/faker/tv_shows/breaking_bad.rb index b2e91d9a55..c6e2059df6 100644 --- a/lib/faker/tv_shows/breaking_bad.rb +++ b/lib/faker/tv_shows/breaking_bad.rb @@ -6,10 +6,28 @@ class BreakingBad < Base flexible :breaking_bad class << self + ## + # Produces the name of a character from Breaking Bad. + # + # @return [String] + # + # @example + # Faker::TvShows::BreakingBad.character #=> "Walter White" + # + # @faker.version 1.8.8 def character fetch('breaking_bad.character') end + ## + # Produces the name of an episode from Breaking Bad. + # + # @return [String] + # + # @example + # Faker::TvShows::BreakingBad.episode #=> "Fly" + # + # @faker.version 1.8.8 def episode fetch('breaking_bad.episode') end