YARD annotation: fix example, markup (vcr#803)

* YARD annotation: fix example, markup

* YARD annotation: avoid warnings

* YARD annotation: Avoid warning

 - this compacts away the "invented" last element for options

* Avoid YARD warning in CHANGELOG.md

CHANGELOG.md

@@ -362,7 +362,7 @@ Bug Fixes:
   * Add Faraday hook that automatically inserts the VCR middleware so that you can use VCR with Faraday without needing to insert the middleware yourself. Use `VCR.configure { |c| c.hook_into :faraday }`.
   * Add `ignore_request` config option. Pass it a block that returns true if the given request should be ignored.
   * Improve the unhandled HTTP request error message so that it lists different options for how to get VCR to handle it.
-  * Add {before,after,around}_http_request hooks.
+  * Add `{before,after,around}_http_request` hooks.
   * Updated WebMock integration and bumped up required version to 1.7.8.
   * Test against latest Excon (0.7.9) and confirm that VCR works fine with it.
   * Add define_cassette_placeholder as an alias for filter_sensitive_data.

lib/vcr.rb

@@ -203,13 +203,13 @@ def use_cassette(name, options = {}, &block)
   # Inserts multiple cassettes the given names
   #
   # @example
-  # cassettes = [
-  #  { name: 'github' },
-  #  { name: 'apple', options: { erb: true } }
-  # ]
-  # VCR.use_cassettes() do
-  #   # make multiple HTTP requests
-  # end
+  #   cassettes = [
+  #    { name: 'github' },
+  #    { name: 'apple', options: { erb: true } }
+  #   ]
+  #   VCR.use_cassettes(cassettes) do
+  #     # make multiple HTTP requests
+  #   end
   def use_cassettes(cassettes, &block)
     cassette = cassettes.pop
     use_cassette(cassette[:name], cassette[:options] || {}) do

lib/vcr/linked_cassette.rb

@@ -9,8 +9,8 @@ class CassetteList
       include Enumerable
 
       # Creates a new list of context-owned cassettes and linked cassettes
-      # @param [Array] context-owned cassettes
-      # @param [Array] context-unowned (linked) cassettes
+      # @param cassettes [Array] context-owned cassettes
+      # @param linked_cassettes [Array] context-unowned (linked) cassettes
       def initialize(cassettes, linked_cassettes)
         @cassettes = cassettes
         @linked_cassettes = linked_cassettes
@@ -52,8 +52,8 @@ def wrap(cassette)
     end
 
     # Create a new CassetteList
-    # @param [Array] context-owned cassettes
-    # @param [Array] context-unowned (linked) cassettes
+    # @param cassettes [Array] context-owned cassettes
+    # @param linked_cassettes [Array] context-unowned (linked) cassettes
     def self.list(cassettes, linked_cassettes)
       CassetteList.new(cassettes, linked_cassettes)
     end

lib/vcr/test_frameworks/cucumber.rb

@@ -23,10 +23,10 @@ def initialize(main_object)
     # Adds `Before` and `After` cucumber hooks for the named tags that
     # will cause a VCR cassette to be used for scenarios with matching tags.
     #
-    # @param [Array<String>] tag_names the cucumber scenario tags
-    # @param [(optional) Hash] options the cassette options. Specify
-    #   `:use_scenario_name => true` to automatically name the
-    #   cassette according to the scenario name.
+    # @param tag_names [Array<String,Hash>] the cucumber scenario tags. If
+    #  the last argument is a hash it is treated as cassette options.
+    #   - `:use_scenario_name => true` to automatically name the
+    #     cassette according to the scenario name.
     def tags(*tag_names)
       original_options = tag_names.last.is_a?(::Hash) ? tag_names.pop : {}
       tag_names.each do |tag_name|