Yard powered docs (#1553)

* install Yard * add some basic docs to test with * and go go gadget yard * Revert "and go go gadget yard" This reverts commit b2c8000. * use square brackets not braces * fully document Faker::Blockchain * exclude deprecated methods * add version numbers to blockchain * update documentation to match what was discussed in #1330 * remove class level @faker.version from docs * update CONTRIBUTING.md * add documentation to Alphanumeric * consistently use braces for types * document the Books namespace * add doc url * Add yard docs for Faker::Blockchain::Tezos.block * update docs for named params * convert back to [] for types Although YARD supports any kind of bracket for the Typing, square brackets are used in the documentation. For those contributing, and unfamiliar with YARD, it would be best that our documentation matches the same style as that in YARD's tutorials and documentation. * document Faker::Creature::Animal * document Faker::Creature::Cat * document Faker::Creature::Dog * document Faker::Creature::Horse * Update lib/faker/default/alphanumeric.rb Co-Authored-By: Connor Shea <[email protected]> * Update lib/faker/creature/dog.rb Co-Authored-By: Connor Shea <[email protected]> * document Faker::Game * document Faker::Games::HalfLife * document Faker::Games::Zelda * document Faker::Games::SuperSmashBros * document Faker::TvShows::BreakingBad * Document Faker::Games::ElderScrolls * document Faker::Gender * document Faker::House * document Faker::ProgrammingLanguage * document Faker::Source * Update some of the docs to use examples without titles. * Update a few more docs to use examples without titles. * Update more docs to use title-less examples. * document Faker::Boolean * document Faker::Avatar * document Faker::Games::Fallout * document Faker::Games::Overwatch * document Faker::Hacker * Fix a method description. * Remove trailing whitespace. * document Faker::App * Add faker version for BreakingBad methods. * Add faker version to Zelda methods. * document Faker::Artist * Merge the examples for semantic_version in app.rb. * Add faker versions for elder_scrolls.rb and fallout.rb. Some of the Elder Scrolls methods were added after others, in 1.9.0. * Update version tags in Elder Scrolls and Fallout. * Clean up docs Co-Authored-By: Connor Shea <[email protected]> Update CONTRIBUTING.md to match new example format install Yard and go go gadget yard Revert "and go go gadget yard" This reverts commit b2c8000. fully document Faker::Blockchain exclude deprecated methods add version numbers to blockchain update documentation to match what was discussed in #1330 remove class level @faker.version from docs update CONTRIBUTING.md update existing yard docs clean up some of the docs * fix line ending issues
faker-ruby · Sep 11, 2019 · f9798d5 · f9798d5
1 parent 9be8cfd
commit f9798d5
Show file tree

Hide file tree

Showing 37 changed files with 1,218 additions and 104 deletions.
diff --git 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
@@ -0,0 +1,5 @@
+--no-private
+--tag faker.version:"Available since"
+--exclude lib/faker/deprecate/
+--output-dir yard_docs
+lib/**/*.rb
diff --git 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)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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)