trav3 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e960e26b64d4fb70cdc4f624b38a03c2816a75d845fa5a8fe21a77b727c7bfb
-  data.tar.gz: 1329f0bc0b2543ee82802a78d0b9c3d09104bb38492390fd268f7a123094e372
+  metadata.gz: b6ce7da3671a152eb6cc9bc85f50d37d8aec27c17ff9c880d168d16e8ff78dff
+  data.tar.gz: 1d01ba5af7ad9bb160e92e975dd9ab0120d041da253580146113b2862675755e
 SHA512:
-  metadata.gz: b7794066686ff59ffc89869566a2fbfc26242bb790ebabd91db9f05c4b6f2317d73245507d814a55a0e7cb56d038345237a92dc6698ef5fff17bf0c0f710cd10
-  data.tar.gz: 33e4c6dcaa3ec4acd45645eef5da239265aa9a231ca16dcf23d283bc0e004c4a97d051cf44287495e84657ef8cd5e94cccca3ab5d6cdf7579514df28c8110a8e
+  metadata.gz: 2d840ae84e3064ec94d4eead9d1adb44d8ac70cbf8f06152cbcbd5be795bbf65d8b7b84979e48f11b541e1f8f0ab4f21baea61b520c02b69c1512f00eeb142ce
+  data.tar.gz: a43e53a52a2a6eb16d776532d0f2cf5dd208f84f7bbabda4f29a4c145056a96953285a27ebc3017b9b64968ca90b7e778cdaf6972f11c5331a7c5c1e4058a1e1

data/.travis.yml

@@ -4,7 +4,7 @@ cache: bundler
 rvm:
 - 2.4.5
 - 2.5.3
-- 2.6.0
+- 2.6.1
 
 env:
   global:

data/README.md

@@ -1,6 +1,6 @@
 [![Gem Version](https://badge.fury.io/rb/trav3.svg)](http://badge.fury.io/rb/trav3)
 [![Build Status](https://travis-ci.org/danielpclark/trav3.svg?branch=master)](https://travis-ci.org/danielpclark/trav3)
-[![Commits Since Release](https://img.shields.io/github/commits-since/danielpclark/trav3/v0.4.1.svg)](https://github.com/danielpclark/trav3/graphs/commit-activity)
+[![Commits Since Release](https://img.shields.io/github/commits-since/danielpclark/trav3/v0.5.0.svg)](https://github.com/danielpclark/trav3/graphs/commit-activity)
 [![Maintainability](https://api.codeclimate.com/v1/badges/1ed07a4baea3832b6207/maintainability)](https://codeclimate.com/github/danielpclark/trav3/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/1ed07a4baea3832b6207/test_coverage)](https://codeclimate.com/github/danielpclark/trav3/test_coverage)
 [![Red The Docs](https://img.shields.io/badge/Read-the%20docs-blue.svg)](http://danielpclark.github.io/trav3/Trav3/Travis.html)
@@ -8,10 +8,14 @@
 
 # Trav3
 
-A simple abstraction layer for Travis CI API v3. The results from queries return either `Success`
-or `RequestError` which both repsond with Hash like query methods for the JSON data or the Net::HTTP
-resonse object methods.
+A simple abstraction layer for Travis CI API v3.
 
+The benefits of this library over the official gem are:
+
+* No gem dependencies
+* Designed much like the API documentation
+* Handling the returned data is the same for nearly every response
+* Little to no learning curve
 
 ## Installation
 
@@ -108,13 +112,70 @@ builds.page.last
 # Recommended inspection
 builds.keys
 builds.dig("some_key")
-```
 
-#### Follow
+# Follow `@href`
+repositories = project.repositories("owner")['repositories']
+repositories.first.follow
+```
 
-Each request returns a `Trav3::Response` type of either `Trav3::Success` or `Trav3::RequestError`.
-When you have an instance of `Trav3::Success` each response collection of either `Hash` or `Array` will
-be an instance of `Trav3::ResponseCollection`.  If the `#hash?` method responds as `true` the `#follow`
+## Response
+
+The results from queries return either `Success` or `RequestError` which both repsond with Hash like query methods for the JSON data or the Net::HTTP resonse object methods.
+
+The `Response` classes `Success` and `RequestError` forward method calls for all of the instance methods of a `ResponseCollection` to the collection.  And for the actual Net::HTTP response the following methods are forwarded from these classes to it:
+
+* `#code`
+* `#code_type`
+* `#uri`
+* `#message`
+* `#read_header`
+* `#header`
+* `#value`
+* `#entity`
+* `#response`
+* `#body`
+* `#decode_content`
+* `#msg`
+* `#reading_body`
+* `#read_body`
+* `#http_version`
+* `#connection_close?`
+* `#connection_keep_alive?`
+* `#initialize_http_header`
+* `#get_fields`
+* `#each_header`
+
+The keys for the response are displayed with `#inspect` along with the object.  Opening up any of the items from its key will produce a [`ResponseCollection`](http://danielpclark.github.io/trav3/Trav3/ResponseCollection.html) object that behaves like both an Array or Hash and has a method to [follow](https://github.com/danielpclark/trav3#follow) response links.
+
+`ResponseCollection` uniformly implements:
+
+* `#[]`
+* `#dig`
+* `#each`
+* `#fetch`
+* `#first`
+* `#follow`
+* `#hash?`
+* `#last`
+
+Which each behave as they would on the collection type per collection type, `Hash` or `Array`, with the exception of `#each`.  `#each` will wrap every item in an `Array` with another `ResponseCollection`, but if it's a `Hash` then `#each` simply works as it normally would on a `Hash`
+
+`ResponseCollection` also forwards:
+
+* `#count`
+* `#keys`
+* `#values`
+* `#has_key?`
+* `#key?`
+* `empty?`
+
+to the inner collection.
+
+## Follow
+
+Each request returns a `Response` type of either `Success` or `RequestError`.
+When you have an instance of `Success` each response collection of either `Hash` or `Array` will
+be an instance of `ResponseCollection`.  If the `#hash?` method responds as `true` the `#follow`
 method will follow any immediate `@href` link provided in the collection.  If `#hash?` produces `false`
 then the collection is an Array of items and you may use the index of the item you want to follow the
 `@href` with; like so `#follow(3)`.

data/lib/trav3.rb

@@ -14,6 +14,68 @@ require 'trav3/rest'
 module Trav3
   # An abstraction for the Travis CI v3 API
   #
+  #
+  # You can get started with the following.
+  #
+  # ```ruby
+  # require 'trav3'
+  # project = Trav3::Travis.new("name/example")
+  # ```
+  #
+  # When you instantiate an instance of `Travis`
+  # you get some default headers and default options.
+  #
+  # #### Default Options
+  #
+  # * `limit: 25` - for limiting data queries to 25 items at most
+  #
+  # Options can be changed via the {#options} getter method which will give you a
+  # {Options} instance. All changes to it affect the options that the `Travis`
+  # instance will submit in url requests.
+  #
+  # #### Default Headers
+  #
+  # * `'Content-Type': 'application/json'`
+  # * `'Accept': 'application/json'`
+  # * `'Travis-API-Version': 3`
+  #
+  # Headers can be changed via the {#headers} getter method which will give you a
+  # {Headers} instance. All changes to it affect the headers that the `Travis`
+  # instance will submit in url requests.
+  #
+  # #### General Usage
+  #
+  # ```ruby
+  # project.owner
+  # project.owner("owner")
+  # project.repositories
+  # project.repositories("owner")
+  # project.repository
+  # project.repository("owner/repo")
+  # project.builds
+  # project.build(12345)
+  # project.build_jobs(12345)
+  # project.job(1234)
+  # project.log(1234)
+  #
+  # # API Request Options
+  # project.options.build({limit: 25})
+  #
+  # # Pagination
+  # builds = project.builds
+  # builds.page.next
+  # builds.page.first
+  # builds.page.last
+  #
+  # # Recommended inspection
+  # builds.keys
+  # builds.dig("some_key")
+  #
+  # # Follow `@href`
+  # repositories = project.repositories("owner")['repositories']
+  # repositories.first.follow
+  # ```
+  #
   # @author Daniel P. Clark https://6ftdan.com
   # @!attribute [r] api_endpoint
   #   @return [String] API endpoint
@@ -113,6 +175,14 @@ module Trav3
     #
     #     Example: GET /owner/danielpclark/active
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.active
+    # # or
+    # travis.active('danielpclark')
+    # ```
+    #
     # GET <code>/owner/{user.login}/active</code>
     #
     #     Template Variable  Type    Description
@@ -122,6 +192,14 @@ module Trav3
     #
     #     Example: GET /owner/danielpclark/active
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.active
+    # # or
+    # travis.active('danielpclark')
+    # ```
+    #
     # GET <code>/owner/{organization.login}/active</code>
     #
     #     Template Variable   Type    Description
@@ -131,6 +209,12 @@ module Trav3
     #
     #     Example: GET /owner/travis-ci/active
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.active('travis-ci')
+    # ```
+    #
     # GET <code>/owner/github_id/{owner.github_id}/active</code>
     #
     #     Template Variable  Type     Description
@@ -140,6 +224,12 @@ module Trav3
     #
     #     Example: GET /owner/github_id/639823/active
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.active(639_823)
+    # ```
+    #
     # @param owner [String] username, organization name, or github id
     # @return [Success, RequestError]
     def active(owner = username)
@@ -184,6 +274,19 @@ module Trav3
     #     beta_feature.id       Integer  Value uniquely identifying the beta feature.
     #     beta_feature.enabled  Boolean  Indicates if the user has this feature turned on.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    #
+    # # Enable comic-sans for user id 119240
+    # travis.beta_feature(:enable, 3, 119_240)
+    #
+    # # Disable comic-sans for user id 119240
+    # travis.beta_feature(:disable, 3, 119_240)
+    # ```
+    #
     # **Delete**
     #
     # This will delete a user's beta feature.
@@ -194,6 +297,16 @@ module Trav3
     #     user.id            Integer  Value uniquely identifying the user.
     #     beta_feature.id    Integer  Value uniquely identifying the beta feature.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    #
+    # # Disable comic-sans via delete for user id 119240
+    # travis.beta_feature(:delete, 3, 119_240)
+    # ```
+    #
     # @param action [Symbol] either `:enable`, `:disable` or `:delete`
     # @param beta_feature_id [String, Integer] id for the beta feature
     # @param user_id [String] user id
@@ -233,6 +346,12 @@ module Trav3
     #
     #     Example: GET /user/119240/beta_features
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.beta_features(119_240)
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @param user_id [String, Integer] user id
@@ -288,6 +407,12 @@ module Trav3
     #
     #     Example: GET /repo/891/branch/master
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.branch('master')
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/branch/{branch.name}</code>
     #
     #     Template Variable  Type    Description
@@ -298,6 +423,12 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/branch/master
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.branch('master')
+    # ```
+    #
     # @param name [String] the branch name for the current repository
     # @return [Success, RequestError]
     def branch(name)
@@ -348,6 +479,13 @@ module Trav3
     # **Sortable by:** <code>name</code>, <code>last_build</code>, <code>exists_on_github</code>, <code>default_branch</code>, append <code>:desc</code> to any attribute to reverse order.
     # The default value is <code>default_branch</code>,<code>exists_on_github</code>,<code>last_build:desc</code>.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5, exists_on_github: true})
+    # travis.branches
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/branches</code>
     #
     #     Template Variable  Type    Description
@@ -365,6 +503,13 @@ module Trav3
     # **Sortable by:** <code>name</code>, <code>last_build</code>, <code>exists_on_github</code>, <code>default_branch</code>, append <code>:desc</code> to any attribute to reverse order.
     # The default value is <code>default_branch</code>,<code>exists_on_github</code>,<code>last_build:desc</code>.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5, exists_on_github: true})
+    # travis.branches
+    # ```
+    #
     # @return [Success, RequestError]
     def branches
       get("#{with_repo}/branches#{opts}")
@@ -404,6 +549,13 @@ module Trav3
     #
     #     Example: GET /broadcasts
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.broadcasts
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @return [Success, RequestError]
@@ -471,6 +623,12 @@ module Trav3
     #
     #     Example: GET /build/86601346
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.build(351_778_872)
+    # ```
+    #
     # **Cancel**
     #
     # This cancels a currently running build. It will set the build and associated jobs to "state": "canceled".
@@ -482,6 +640,13 @@ module Trav3
     #
     #     Example: POST /build/86601346/cancel
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.build(478_772_528, :cancel)
+    # ```
+    #
     # **Restart**
     #
     # This restarts a build that has completed or been canceled.
@@ -493,6 +658,13 @@ module Trav3
     #
     #     Example: POST /build/86601346/restart
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.build(478_772_528, :restart)
+    # ```
+    #
     # @note POST requests require an authorization token set in the headers. See: {authorization=}
     #
     # @param build_id [String, Integer] the build id number
@@ -565,6 +737,14 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>started_at</code>, <code>finished_at</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.builds(false)
+    # ```
+    #
     # **Find**
     #
     # This returns a list of builds for an individual repository. It is possible to use the repository id or slug in the request. The result is paginated. Each request will return 25 results.
@@ -593,6 +773,13 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>started_at</code>, <code>finished_at</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5})
+    # travis.builds
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/builds</code>
     #
     #     Template Variable  Type    Description
@@ -617,9 +804,20 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>started_at</code>, <code>finished_at</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5})
+    # travis.builds
+    # ```
+    #
+    # @note requests may require an authorization token set in the headers. See: {authorization=}
+    #
+    # @param repo [Boolean] If true get repo builds, otherwise get user builds
     # @return [Success, RequestError]
-    def builds
-      get("#{with_repo}/builds#{opts}")
+    def builds(repo = true)
+      repo and return get("#{with_repo}/builds#{opts}")
+      get("#{without_repo}/builds#{opts}")
     end
 
     # A list of jobs.
@@ -666,6 +864,12 @@ module Trav3
     #
     #     Example: GET /build/86601346/jobs
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.build_jobs(86_601_346)
+    # ```
+    #
     # **For Current User**
     #
     # This returns a list of jobs a current user has access to.
@@ -689,10 +893,21 @@ module Trav3
     # **Sortable by:** <code>id</code>, append <code>:desc</code> to any attribute to reverse order.
     # The default value is id:desc.
     #
-    # @param build_id [String, Integer] the build id number
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.build_jobs(false)
+    # ```
+    #
+    # @note requests may require an authorization token set in the headers. See: {authorization=}
+    #
+    # @param build_id [String, Integer, Boolean] the build id number.  If falsey then get all jobs for current user
     # @return [Success, RequestError]
     def build_jobs(build_id)
-      get("#{without_repo}/build/#{build_id}/jobs")
+      build_id and return get("#{without_repo}/build/#{build_id}/jobs")
+      get("#{without_repo}/jobs#{opts}")
     end
 
     # A list of caches.
@@ -721,6 +936,14 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/caches?branch=master
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({branch: :master})
+    # travis.caches
+    # ```
+    #
     # ```bash
     # curl \
     #   -H "Content-Type: application/json" \
@@ -729,6 +952,14 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/caches?match=linux
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({match: :linux})
+    # travis.caches
+    # ```
+    #
     # GET <code>/repo/{repository.id}/caches</code>
     #
     #     Template Variable  Type     Description
@@ -769,6 +1000,14 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/caches?branch=master
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({branch: :master})
+    # travis.caches(:delete)
+    # ```
+    #
     # DELETE <code>/repo/{repository.id}/caches</code>
     #
     #     Template Variable  Type     Description
@@ -788,8 +1027,10 @@ module Trav3
     # @param delete [Boolean] option for deleting cache(s)
     # @return [Success, RequestError]
     def caches(delete = false)
-      delete and return without_limit { delete("#{with_repo}/caches#{opts}") }
-      get("#{with_repo}/caches")
+      without_limit do
+        delete and return delete("#{with_repo}/caches#{opts}")
+        get("#{with_repo}/caches#{opts}")
+      end
     end
 
     # An individual cron. There can be only one cron per branch on a repository.
@@ -833,6 +1074,13 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.cron(id: 78_199)
+    # ```
+    #
     # **Delete**
     #
     # This deletes a single cron.
@@ -842,6 +1090,13 @@ module Trav3
     #     Template Variable  Type     Description
     #     cron.id            Integer  Value uniquely identifying the cron.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.cron(id: 78_199, delete: true)
+    # ```
+    #
     # **For Branch**
     #
     # This returns the cron set for the specified branch for the specified repository. It is possible to use the repository id or slug in the request.
@@ -856,6 +1111,13 @@ module Trav3
     #
     #     Example: GET /repo/891/branch/master/cron
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.cron(branch_name: 'master')
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/branch/{branch.name}/cron</code>
     #
     #     Template Variable  Type    Description
@@ -866,6 +1128,13 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/branch/master/cron
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.cron(branch_name: 'master')
+    # ```
+    #
     # **Create**
     #
     # This creates a cron on the specified branch for the specified repository. It is possible to use the repository id or slug in the request. Content-Type MUST be set in the header and an interval for the cron MUST be specified as a parameter.
@@ -879,6 +1148,13 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/branch/master/cron
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.cron(branch_name: 'master', create: { 'interval' => 'monthly' })
+    # ```
+    #
     # POST <code>/repo/{repository.id}/branch/{branch.name}/cron</code>
     #
     #     Template Variable  Type     Description
@@ -960,6 +1236,14 @@ module Trav3
     #
     #     Example: GET /repo/891/crons?limit=5
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.crons
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/crons</code>
     #
     #     Template Variable  Type    Description
@@ -971,9 +1255,17 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/crons?limit=5
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.crons
+    # ```
+    #
     # @return [Success, RequestError]
     def crons
-      get("#{with_repo}/crons")
+      get("#{with_repo}/crons#{opts}")
     end
 
     # POST <code>/repo/{repository.id}/email_subscription</code>
@@ -983,6 +1275,13 @@ module Trav3
     #
     #     Example: POST /repo/891/email_subscription
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.email_resubscribe
+    # ```
+    #
     # POST <code>/repo/{repository.slug}/email_subscription</code>
     #
     #     Template Variable  Type    Description
@@ -990,6 +1289,13 @@ module Trav3
     #
     #     Example: POST /repo/rails%2Frails/email_subscription
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.email_resubscribe
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @return [Success, RequestError]
@@ -1004,6 +1310,13 @@ module Trav3
     #
     #     Example: DELETE /repo/891/email_subscription
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.email_unsubscribe
+    # ```
+    #
     # DELETE <code>/repo/{repository.slug}/email_subscription</code>
     #
     #     Template Variable  Type    Description
@@ -1011,6 +1324,13 @@ module Trav3
     #
     #     Example: DELETE /repo/rails%2Frails/email_subscription
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.email_unsubscribe
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @return [Success, RequestError]
@@ -1060,6 +1380,13 @@ module Trav3
     #     include          [String]  List of attributes to eager load.
     #     repository.id    Integer   Value uniquely identifying the repository.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c')
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/env_var/{env_var.id}</code>
     #
     #     Template Variable  Type    Description
@@ -1071,6 +1398,13 @@ module Trav3
     #     include          [String]  List of attributes to eager load.
     #     repository.id    Integer   Value uniquely identifying the repository.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c')
+    # ```
+    #
     # **Update**
     #
     # This updates a single environment variable. It is possible to use the repository id or slug in the request.
@@ -1086,6 +1420,13 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/{env_var.id}
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c', update: { value: 'bar', public: false })
+    # ```
+    #
     # PATCH <code>/repo/{repository.id}/env_var/{env_var.id}</code>
     #
     #     Template Variable  Type     Description
@@ -1116,12 +1457,26 @@ module Trav3
     #     repository.id      Integer  Value uniquely identifying the repository.
     #     env_var.id         String   The environment variable id.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c', delete: true)
+    # ```
+    #
     # DELETE <code>/repo/{repository.slug}/env_var/{env_var.id}</code>
     #
     #     Template Variable  Type    Description
     #     repository.slug    String  Same as {repository.owner.name}/{repository.name}.
     #     env_var.id         String  The environment variable id.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c', delete: true)
+    # ```
+    #
     # @overload env_var(env_var_id)
     #   Gets current env var
     #   @param env_var_id [String] environment variable id
@@ -1165,6 +1520,13 @@ module Trav3
     #
     #     Example: GET /repo/891/env_vars
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_vars
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/env_vars</code>
     #
     #     Template Variable  Type    Description
@@ -1174,6 +1536,13 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/env_vars
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_vars
+    # ```
+    #
     # **Create**
     #
     # This creates an environment variable for an individual repository. It is possible to use the repository id or slug in the request.
@@ -1189,6 +1558,13 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/env_vars
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.env_vars(name: 'FOO', value: 'bar', public: false)
+    # ```
+    #
     # POST <code>/repo/{repository.id}/env_vars</code>
     #
     #     Template Variable  Type     Description
@@ -1254,6 +1630,14 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.installation(617_754)
+    # ```
+    #
     # @param installation_id [String, Integer] GitHub App installation id
     # @return [Success, RequestError]
     def installation(installation_id)
@@ -1309,6 +1693,13 @@ module Trav3
     #
     #     Example: GET /job/86601347
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.job(351_778_875)
+    # ```
+    #
     # **Cancel**
     #
     # This cancels a currently running job.
@@ -1320,6 +1711,13 @@ module Trav3
     #
     #     Example: POST /job/86601347/cancel
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.job(351_778_875, :cancel)
+    # ```
+    #
     # **Restart**
     #
     # This restarts a job that has completed or been canceled.
@@ -1331,6 +1729,13 @@ module Trav3
     #
     #     Example: POST /job/86601347/restart
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.job(351_778_875, :restart)
+    # ```
+    #
     # **Debug**
     #
     # This restarts a job in debug mode, enabling the logged-in user to ssh into the build VM. Please note this feature is only available on the travis-ci.com domain, and those repositories on the travis-ci.org domain for which the debug feature is enabled. See this document for more details.
@@ -1342,7 +1747,16 @@ module Trav3
     #
     #     Example: POST /job/86601347/debug
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.job(351_778_875, :debug)
+    # ```
+    #
     # @note POST requests require an authorization token set in the headers. See: {authorization=}
+    # @note **Debug** is only available on the travis-ci.com domain, and those repositories on the travis-ci.org domain for which the debug feature is enabled.
     #
     # @param job_id [String, Integer] the job id number
     # @param option [Symbol] options for :cancel, :restart, or :debug
@@ -1399,6 +1813,14 @@ module Trav3
     #
     #     Example: GET /repo/891/key_pair
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/key_pair</code>
     #
     #     Template Variable  Type    Description
@@ -1408,6 +1830,14 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/key_pair
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair
+    # ```
+    #
     # **Create**
     #
     # Creates a new key pair.
@@ -1421,6 +1851,14 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/key_pair
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair(create: { description: 'FooBar', value: OpenSSL::PKey::RSA.generate(2048).to_s })
+    # ```
+    #
     # POST <code>/repo/{repository.id}/key_pair</code>
     #
     #     Template Variable  Type     Description
@@ -1454,6 +1892,14 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/key_pair
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair(update: { description: 'FooBarBaz' })
+    # ```
+    #
     # PATCH <code>/repo/{repository.id}/key_pair</code>
     #
     #     Template Variable  Type     Description
@@ -1485,6 +1931,14 @@ module Trav3
     #
     #     Example: DELETE /repo/891/key_pair
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair(delete: true)
+    # ```
+    #
     # DELETE <code>/repo/{repository.slug}/key_pair</code>
     #
     #     Template Variable  Type    Description
@@ -1492,6 +1946,14 @@ module Trav3
     #
     #     Example: DELETE /repo/rails%2Frails/key_pair
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair(delete: true)
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     # @note API enpoint needs to be set to `https://api.travis-ci.com` See: {api_endpoint=}
     #
@@ -1551,6 +2013,14 @@ module Trav3
     #
     #     Example: GET /repo/891/key_pair/generated
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair_generated
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/key_pair/generated</code>
     #
     #     Template Variable  Type    Description
@@ -1560,6 +2030,14 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/key_pair/generated
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair_generated
+    # ```
+    #
     # **Create**
     #
     # Generate a new key pair, replacing the previous one.
@@ -1571,6 +2049,14 @@ module Trav3
     #
     #     Example: POST /repo/891/key_pair/generated
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair_generated(:create)
+    # ```
+    #
     # POST <code>/repo/{repository.slug}/key_pair/generated</code>
     #
     #     Template Variable  Type    Description
@@ -1578,6 +2064,14 @@ module Trav3
     #
     #     Example: POST /repo/rails%2Frails/key_pair/generated
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.api_endpoint = 'https://api.travis-ci.com'
+    # travis.authorization = 'xxxx'
+    # travis.key_pair_generated(:create)
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @param action [String, Symbol] defaults to getting current key pair, use `:create` if you would like to generate a new key pair
@@ -1605,6 +2099,12 @@ module Trav3
     #
     #     Example: POST /lint
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.lint(File.read('.travis.yml'))
+    # ```
+    #
     # @param yaml_content [String] the contents for the file `.travis.yml`
     # @return [Success, RequestError]
     def lint(yaml_content)
@@ -1649,6 +2149,14 @@ module Trav3
     #       -H "Authorization: token xxxxxxxxxxxx" \
     #       https://api.travis-ci.org/job/{job.id}/log
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.log(351_778_875)
+    # # or
+    # travis.log(351_778_875, :text)
+    # ```
+    #
     # The default response type is application/json, and will include additional meta data such as @type, @representation etc. (see [https://developer.travis-ci.org/format](https://developer.travis-ci.org/format)).
     #
     # GET <code>/job/{job.id}/log</code>
@@ -1682,6 +2190,13 @@ module Trav3
     #       -H "Authorization: token xxxxxxxxxxxx" \
     #       https://api.travis-ci.org/job/{job.id}/log
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.log(478_772_530, :delete)
+    # ```
+    #
     # DELETE <code>/job/{job.id}/log</code>
     #
     #     Template Variable  Type     Description
@@ -1737,6 +2252,13 @@ module Trav3
     #     limit            Integer   How many messages to include in the response. Used for pagination.
     #     offset           Integer   How many messages to skip before the first entry in the response. Used for pagination.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.messages(147_731_561)
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/request/{request.id}/messages</code>
     #
     #     Template Variable  Type     Description
@@ -1747,6 +2269,13 @@ module Trav3
     #     limit            Integer   How many messages to include in the response. Used for pagination.
     #     offset           Integer   How many messages to skip before the first entry in the response. Used for pagination.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.messages(147_731_561)
+    # ```
+    #
     # @param request_id [String, Integer] the request id
     # @return [Success, RequestError]
     def messages(request_id)
@@ -1801,6 +2330,12 @@ module Trav3
     #
     #     Example: GET /org/87
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.organization(87)
+    # ```
+    #
     # @param org_id [String, Integer] the organization id
     # @raise [TypeError] if given organization id is not a number
     # @return [Success, RequestError]
@@ -1852,9 +2387,17 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>login</code>, <code>name</code>, <code>github_id</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.organizations
+    # ```
+    #
     # @return [Success, RequestError]
     def organizations
-      get("#{without_repo}/orgs")
+      get("#{without_repo}/orgs#{opts}")
     end
 
     # This will be either a {https://developer.travis-ci.com/resource/user user} or {https://developer.travis-ci.com/resource/organization organization}.
@@ -1901,6 +2444,15 @@ module Trav3
     #
     #     Example: GET /owner/danielpclark
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.owner
+    # # or
+    # travis.owner('danielpclark')
+    # ```
+    #
     # GET <code>/owner/{user.login}</code>
     #
     #     Template Variable  Type      Description
@@ -1911,6 +2463,15 @@ module Trav3
     #
     #     Example: GET /owner/danielpclark
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.owner
+    # # or
+    # travis.owner('danielpclark')
+    # ```
+    #
     # GET <code>/owner/{organization.login}</code>
     #
     #     Template Variable   Type      Description
@@ -1921,6 +2482,13 @@ module Trav3
     #
     #     Example: GET /owner/travis-ci
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.owner('travis-ci')
+    # ```
+    #
     # GET <code>/owner/github_id/{owner.github_id}</code>
     #
     #     Template Variable   Type      Description
@@ -1931,6 +2499,13 @@ module Trav3
     #
     #     Example: GET /owner/github_id/639823
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.owner(639_823)
+    # ```
+    #
     # @param owner [String] username or github id
     # @return [Success, RequestError]
     def owner(owner = username)
@@ -1938,7 +2513,7 @@ module Trav3
       get("#{without_repo}/owner/#{owner}")
     end
 
-    # Document `resources/preference/overview` not found.
+    # Individual preferences for current user or organization.
     #
     # ## Attributes
     #
@@ -1962,7 +2537,7 @@ module Trav3
     #
     # **For Organization**
     #
-    # Document `resources/preference/actions/for_organization` not found.
+    # Get preference for organization.
     #
     # GET <code>/org/{organization.id}/preference/{preference.name}</code>
     #
@@ -1972,9 +2547,16 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.preference('private_insights_visibility', org_id: 107_660)
+    # ```
+    #
     # **Update**
     #
-    # Document `resources/preference/actions/update` not found.
+    # Set preference for organization.
     #
     # PATCH <code>/org/{organization.id}/preference/{preference.name}</code>
     #
@@ -1984,6 +2566,15 @@ module Trav3
     #     Accepted Parameter  Type     Description
     #     preference.value    Unknown  The preference's value.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.preference('private_insights_visibility', 'admins', org_id: 107_660)
+    # ```
+    #
+    # Set preference for current user.
+    #
     # PATCH <code>/preference/{preference.name}</code>
     #
     #     Template Variable  Type     Description
@@ -1991,9 +2582,16 @@ module Trav3
     #     Accepted Parameter  Type     Description
     #     preference.value    Unknown  The preference's value.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.preference('build_emails', true)
+    # ```
+    #
     # **Find**
     #
-    # Document `resources/preference/actions/find` not found.
+    # Get preference for current user.
     #
     # GET <code>/preference/{preference.name}</code>
     #
@@ -2002,6 +2600,13 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.preference('build_emails')
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @param key [String] preference name to get or set
@@ -2018,7 +2623,7 @@ module Trav3
       get("#{without_repo}#{org_id}/preference/#{key}")
     end
 
-    # Document `resources/preferences/overview` not found.
+    # Preferences for current user or organization.
     #
     # ## Attributes
     #
@@ -2029,7 +2634,7 @@ module Trav3
     #
     # **For Organization**
     #
-    # Document `resources/preferences/actions/for_organization` not found.
+    # Gets preferences for organization.
     #
     # GET <code>/org/{organization.id}/preferences</code>
     #
@@ -2040,9 +2645,16 @@ module Trav3
     #
     #     Example: GET /org/87/preferences
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.preferences(107_660)
+    # ```
+    #
     # **For User**
     #
-    # Document `resources/preferences/actions/for_user` not found.
+    # Gets preferences for current user.
     #
     # GET <code>/preferences</code>
     #
@@ -2051,6 +2663,13 @@ module Trav3
     #
     #     Example: GET /preferences
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.preferences
+    # ```
+    #
     # @note requests require an authorization token set in the headers. See: {authorization=}
     #
     # @param org_id [String, Integer] optional organization id
@@ -2116,6 +2735,15 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5, sort_by: 'active,name'})
+    # travis.repositories
+    # # or
+    # travis.repositories('danielpclark')
+    # ```
+    #
     # GET <code>/owner/{user.login}/repos</code>
     #
     #     Template Variable  Type    Description
@@ -2137,6 +2765,15 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5, sort_by: 'active,name'})
+    # travis.repositories
+    # # or
+    # travis.repositories('danielpclark')
+    # ```
+    #
     # GET <code>/owner/{organization.login}/repos</code>
     #
     #     Template Variable   Type    Description
@@ -2158,6 +2795,14 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5, sort_by: 'active,name'})
+    # travis.repositories('travis-ci')
+    # ```
+    #
     # GET <code>/owner/github_id/{owner.github_id}/repos</code>
     #
     #     Template Variable  Type     Description
@@ -2179,6 +2824,13 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.options.build({limit: 5, sort_by: 'active,name'})
+    # travis.repositories(639_823)
+    # ```
+    #
     # **For Current User**
     #
     # This returns a list of repositories the current user has access to.
@@ -2201,9 +2853,18 @@ module Trav3
     #
     # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order.
     #
-    # @param owner [String] username or github id
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5, sort_by: 'active,name'})
+    # travis.repositories(:self)
+    # ```
+    #
+    # @param owner [String, Integer, Symbol] username, github id, or `:self`
     # @return [Success, RequestError]
     def repositories(owner = username)
+      owner.equal?(:self) and return get("#{without_repo}/repos#{opts}")
       number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}/repos#{opts}")
       get("#{without_repo}/owner/#{owner}/repos#{opts}")
     end
@@ -2253,6 +2914,12 @@ module Trav3
     #
     #     Example: GET /repo/891
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.repository('danielpclark/trav3')
+    # ```
+    #
     # GET <code>/repo/{repository.slug}</code>
     #
     #     Template Variable  Type    Description
@@ -2263,6 +2930,12 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.repository('danielpclark/trav3')
+    # ```
+    #
     # **Activate**
     #
     # This will activate a repository, allowing its tests to be run on Travis CI.
@@ -2274,6 +2947,13 @@ module Trav3
     #
     #     Example: POST /repo/891/activate
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :activate)
+    # ```
+    #
     # POST <code>/repo/{repository.slug}/activate</code>
     #
     #     Template Variable  Type    Description
@@ -2281,6 +2961,13 @@ module Trav3
     #
     #     Example: POST /repo/rails%2Frails/activate
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :activate)
+    # ```
+    #
     # **Deactivate**
     #
     # This will deactivate a repository, preventing any tests from running on Travis CI.
@@ -2292,6 +2979,13 @@ module Trav3
     #
     #     Example: POST /repo/891/deactivate
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :deactivate)
+    # ```
+    #
     # POST <code>/repo/{repository.slug}/deactivate</code>
     #
     #     Template Variable  Type    Description
@@ -2299,6 +2993,13 @@ module Trav3
     #
     #     Example: POST /repo/rails%2Frails/deactivate
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :deactivate)
+    # ```
+    #
     # **Star**
     #
     # This will star a repository based on the currently logged in user.
@@ -2310,6 +3011,13 @@ module Trav3
     #
     #     Example: POST /repo/891/star
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :star)
+    # ```
+    #
     # POST <code>/repo/{repository.slug}/star</code>
     #
     #     Template Variable  Type    Description
@@ -2317,6 +3025,13 @@ module Trav3
     #
     #     Example: POST /repo/rails%2Frails/star
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :star)
+    # ```
+    #
     # **Unstar**
     #
     # This will unstar a repository based on the currently logged in user.
@@ -2328,6 +3043,13 @@ module Trav3
     #
     #     Example: POST /repo/891/unstar
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :unstar)
+    # ```
+    #
     # POST <code>/repo/{repository.slug}/unstar</code>
     #
     #     Template Variable  Type    Description
@@ -2335,6 +3057,13 @@ module Trav3
     #
     #     Example: POST /repo/rails%2Frails/unstar
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.repository('danielpclark/trav3', :unstar)
+    # ```
+    #
     # @note POST requests require an authorization token set in the headers. See: {authorization=}
     #
     # @param repo [String] github_username/repository_name
@@ -2388,7 +3117,7 @@ module Trav3
     #
     # **Find**
     #
-    # Document `resources/request/actions/find` not found.
+    # Get the request by id for the current repository
     #
     # GET <code>/repo/{repository.id}/request/{request.id}</code>
     #
@@ -2398,6 +3127,13 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.request(147_776_757)
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/request/{request.id}</code>
     #
     #     Template Variable  Type     Description
@@ -2406,6 +3142,13 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.request(147_776_757)
+    # ```
+    #
     # @param request_id [String, Integer] request id
     # @return [Success, RequestError]
     def request(request_id)
@@ -2460,6 +3203,14 @@ module Trav3
     #
     #     Example: GET /repo/891/requests?limit=5
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.requests
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/requests</code>
     #
     #     Template Variable  Type    Description
@@ -2471,6 +3222,14 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/requests?limit=5
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.options.build({limit: 5})
+    # travis.requests
+    # ```
+    #
     # **Create**
     #
     # This will create a request for an individual repository, triggering a build to run on Travis CI.
@@ -2487,6 +3246,16 @@ module Trav3
     #   https://api.travis-ci.com/repo/1/requests
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.requests(
+    #   message: 'Override the commit message: this is an api request',
+    #   branch: 'master'
+    # )
+    # ```
+    #
     # The response includes the following body:
     #
     # ```json
@@ -2588,6 +3357,13 @@ module Trav3
     #
     #     Example: GET /build/86601346/stages
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.stages(479_113_572)
+    # ```
+    #
     # @param build_id [String, Integer] build id
     # @raise [TypeError] if given build id is not a number
     # @return [Success, RequestError]
@@ -2640,6 +3416,13 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.setting('auto_cancel_pull_requests')
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/setting/{setting.name}</code>
     #
     #     Template Variable  Type    Description
@@ -2648,6 +3431,13 @@ module Trav3
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.setting('auto_cancel_pull_requests')
+    # ```
+    #
     # **Update**
     #
     # This updates a single setting. It is possible to use the repository id or slug in the request.
@@ -2663,6 +3453,13 @@ module Trav3
     #   https://api.travis-ci.com/repo/1234/setting/{setting.name}
     # ```
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.setting('auto_cancel_pull_requests', false)
+    # ```
+    #
     # PATCH <code>/repo/{repository.id}/setting/{setting.name}</code>
     #
     #     Template Variable  Type     Description
@@ -2727,6 +3524,13 @@ module Trav3
     #
     #     Example: GET /repo/891/settings
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.settings
+    # ```
+    #
     # GET <code>/repo/{repository.slug}/settings</code>
     #
     #     Template Variable  Type    Description
@@ -2736,6 +3540,13 @@ module Trav3
     #
     #     Example: GET /repo/rails%2Frails/settings
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.settings
+    # ```
+    #
     # @return [Success, RequestError]
     def settings
       get("#{with_repo}/settings")
@@ -2790,6 +3601,12 @@ module Trav3
     #
     #     Example: GET /user/119240
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.user(119_240)
+    # ```
+    #
     # **Sync**
     #
     # This triggers a sync on a user's account with their GitHub account.
@@ -2801,6 +3618,13 @@ module Trav3
     #
     #     Example: POST /user/119240/sync
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.user(114_816, :sync)
+    # ```
+    #
     # **Current**
     #
     # This will return information about the current user.
@@ -2812,6 +3636,13 @@ module Trav3
     #
     #     Example: GET /user
     #
+    # ```ruby
+    # # RUBY EXAMPLE
+    # travis = Trav3::Travis.new('danielpclark/trav3')
+    # travis.authorization = 'xxxx'
+    # travis.user
+    # ```
+    #
     # @note sync feature may not be permitted
     # @note POST requests require an authorization token set in the headers. See: {authorization=}
     #