Add yardoc and better documentation

Author: claudiob

.gitignore

@@ -19,3 +19,6 @@ coverage/
 **/tmp
 *.gem
 *.sqlite3
+
+doc/
+.yardoc/

.yardopts

@@ -0,0 +1 @@
+--no-private

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-api-matchers (0.6.1)
+    rspec-api-matchers (0.6.2)
       activesupport
       rack
       rspec
@@ -50,6 +50,7 @@ GEM
       atomic
     tins (0.13.0)
     tzinfo (0.3.38)
+    yard (0.8.7.2)
 
 PLATFORMS
   ruby
@@ -59,3 +60,4 @@ DEPENDENCIES
   coveralls
   rake
   rspec-api-matchers!
+  yard

README.md

@@ -5,7 +5,9 @@ RSpecApi::Matchers lets you express outcomes on the response of web APIs.
 
     expect(response).to have_status(:not_found)
 
-More documentation and examples about RSpecApi are available at [http://rspec-api.github.io](http://rspec-api.github.io)
+The full documentation is available at [rubydoc.info](http://rubydoc.info/github/rspec-api/rspec-api-matchers/master/frames).
+
+More information about the parent project RSpecApi is available at [rspec-api.github.io](http://rspec-api.github.io)
 
 [![Build Status](https://travis-ci.org/rspec-api/rspec-api-matchers.png?branch=master)](https://travis-ci.org/rspec-api/rspec-api-matchers)
 [![Code Climate](https://codeclimate.com/github/rspec-api/rspec-api-matchers.png)](https://codeclimate.com/github/rspec-api/rspec-api-matchers)
@@ -21,10 +23,9 @@ Available matchers
     expect(response).to be_a_collection
     expect(response).to be_wrapped_in_callback('alert')
     expect(response).to be_sorted(by: :id, verse: :desc)
-    expect(response).to be_filtered(by: :id, value: 10)
+    expect(response).to be_filtered(by: :id, value: 10, compare_with: :>)
     expect(response).to have_attributes(id: {value: 1.2}, url: {type: {string: :url}})
 
-
 How to install
 ==============
 
@@ -41,7 +42,6 @@ Indicating the full version in your Gemfile (*major*.*minor*.*patch*) guarantees
 that your project won’t occur in any error when you `bundle update` and a new
 version of RSpecApi::Matchers is released.
 
-
 How to contribute
 =================
 

lib/rspec-api/matchers.rb

@@ -11,6 +11,22 @@
 require 'rspec-api/matchers/status/have_status'
 
 module RSpecApi
+  # Provides RSpec Matchers for RESTful web APIs.
+  #
+  # To have these matchers available inside of an RSpec `describe` block,
+  # tag that block with the `:rspec_api` metadata, or explicitly include the
+  # RSpecApi::Matchers module inside the example group
+  #
+  # @example Tag a `describe` block as `:rspec_api`:
+  #   describe "Artists", rspec_api: true do
+  #      ... # here you can write `expect(response).to have_status :ok`, etc.
+  #   end
+  #
+  # @example Explicitly include the RSpecApi::Matchers module
+  #   describe "Artists" do
+  #      include RSpecApi::Matchers
+  #      ... # here you can write `expect(response).to have_status :ok`, etc.
+  #   end
   module Matchers
     include Attributes
     include Collection
@@ -25,20 +41,4 @@ module Matchers
   end
 end
 
-# RSpecApi::Matchers adds matchers to test RESTful APIs.
-#
-# To have these matchers available inside of an RSpec `describe` block, tag that
-# block with the `:rspec_api` metadata:
-#
-#  describe "Artists", rspec_api: true do
-#     ... # here you can write `expect(response).to have_status :ok`, etc.
-#  end
-RSpec.configuration.include RSpecApi::Matchers, rspec_api: true
-
-# You can also explicitly include the RSpec::Api module inside the example group:
-#
-#  describe "Artists" do
-#     include RSpecApi::Matchers
-#     ... # here you can write `expect(response).to have_status :ok`, etc.
-#  end
-#
+RSpec.configuration.include RSpecApi::Matchers, rspec_api: true

lib/rspec-api/matchers/attributes/have_attributes.rb

@@ -3,18 +3,28 @@
 module RSpecApi
   module Matchers
     module Attributes
-      # Passes if the response body is either a JSON object or a collection of
-      # JSON objects that include all the +attributes+.
+      # Passes if the object includes the expected attributes in the body.
       #
-      # @example
+      # @example Passes if the body is a collection of objects with a URL site
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is an object with a URL-formatted String :site
-      #   response = OpenStruct.new body: '{"site": "http://www.example.com"}'
-      #   expect(response).to have_attributes(site: {type: {string: :url}})
+      #   body = '[{"site": "http://www.foo.com"}, {"site": "http://bar.com"}]'
+      #   obj = OpenStruct.new body: body
       #
-      # For more examples check +have_attributes_spec.rb+.
-
-      # TODO: add &block options
+      #   describe 'have_attributes' do
+      #     include RSpecApi::Matchers::Attributes
+      #     it { expect(obj).to have_attributes(site: {type: {string: :url}}) }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @param [Hash] attributes The expected attributes in the body
+      #
+      # The method works only if the object is a JSON object or a collection of
+      # JSON objects; in the latter case all the objects need to include the
+      # expected attributes for the expectation to pass.
+      #
+      # @see http://git.io/w2dLnw have_attributes_spec.rb for more examples
       def have_attributes(*attributes)
         RSpecApi::Matchers::Attributes::Matcher.new *attributes
       end

lib/rspec-api/matchers/collection/be_a_collection.rb

@@ -3,15 +3,22 @@
 module RSpecApi
   module Matchers
     module Collection
-      # Passes if the response body is a collection of JSON objects
+      # Passes if the object has a collection of JSON objects in the body.
       #
-      # @example
+      # @example Passes if the body is a JSON array
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the body is a JSON array
-      #   body = '[{"id": 1}]'
-      #   expect(OpenStruct.new body: body).to be_a_collection
+      #   body = '[{"id": 1}, {"name": "foo"}, {"name": "bar"}]'
+      #   obj = OpenStruct.new body: body
       #
-      # For more examples check +be_a_collection_spec.rb+.
+      #   describe 'be_a_collection' do
+      #     include RSpecApi::Matchers::Collection
+      #     it { expect(obj).to be_a_collection }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/Bl5qJQ be_a_collection_spec.rb for more examples
       def be_a_collection
         RSpecApi::Matchers::Collection::Matcher.new
       end

lib/rspec-api/matchers/content_type/have_content_type.rb

@@ -3,15 +3,26 @@
 module RSpecApi
   module Matchers
     module ContentType
-      # Passes if the response headers specify the provided content +type+
+      # Passes if the object includes the expected content type in the headers.
       #
-      # @example
+      # @param [Symbol or String] type The expected content type. Can either
+      #   be the exact Content-Type string or just the format. The special
+      #   value +:any+ matches any content type.
+      #
+      # @example Passes if the headers matches the provided JSON content type
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the headers matches the provided JSON content type
       #   headers ={'Content-Type' => 'application/json; charset=utf-8'}
-      #   expect(OpenStruct.new headers: headers).to have_content_type(:json)
+      #   obj = OpenStruct.new headers: headers
+      #
+      #   describe 'have_content_type' do
+      #     include RSpecApi::Matchers::ContentType
+      #     it { expect(obj).to have_content_type(:json) }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
       #
-      # For more examples check +have_content_type_spec.rb+.
+      # @see http://git.io/qwv-RQ have_content_type_spec.rb for more examples
       def have_content_type(type = nil)
         content_type = case type
           when :json then 'application/json; charset=utf-8'

lib/rspec-api/matchers/filter/be_filtered.rb

@@ -3,15 +3,28 @@
 module RSpecApi
   module Matchers
     module Filter
-      # Passes if the response body is a non-empty filtered JSON collection
+      # Passes if the object has a non-empty filtered JSON collection in the body.
       #
-      # @example
+      # @param [Hash] options how the body is expected to be filtered.
+      # @option options [Symbol or String] :by The JSON key to be filtered by
+      # @option options [Object] :value The expected value for the field
+      # @option options [Proc or Symbol] :compare_with (:==) The operator used
+      #   to compare the expected value with the values in the collection
       #
-      #   # Passes if the body only contains objects with ID = 1
-      #   body = '[{"id": 1}, {"id": 1}, {"id": 1}]'
-      #   expect(OpenStruct.new body: body).to be_filtered by: :id, value: 1
+      # @example Passes if the body only contains objects with ID > 1
+      #   require 'rspec-api-matchers'
       #
-      # For more examples check +be_filtered_spec.rb+.
+      #   body = '[{"id": 2}, {"id": 3}]'
+      #   obj = OpenStruct.new body: body
+      #
+      #   describe 'be_filtered' do
+      #     include RSpecApi::Matchers::Filter
+      #     it { expect(obj).to be_filtered by: :id, value: 1, compare_with: :> }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/lHO7nw be_filtered_spec.rb for more examples
       def be_filtered(options = {})
         RSpecApi::Matchers::Filter::Matcher.new options
       end

lib/rspec-api/matchers/headers/have_headers.rb

@@ -3,15 +3,22 @@
 module RSpecApi
   module Matchers
     module Headers
-      # Passes if the response has a non-empty headers Hash.
+      # Passes if the object has a non-empty Hash in the headers.
       #
-      # @example
+      # @example Passes if the headers include the content length
+      #   require 'rspec-api-matchers'
       #
-      #   # Passes if the headers include the content length
       #   headers = {'Content-Length' => 17372}
-      #   expect(OpenStruct.new headers: headers).to have_headers
+      #   obj = OpenStruct.new headers: headers
       #
-      # For more examples check +have_headers_spec.rb+.
+      #   describe 'have_headers' do
+      #     include RSpecApi::Matchers::Headers
+      #     it { expect(obj).to have_headers }
+      #   end
+      #
+      #   # => (rspec) 1 example, 0 failures
+      #
+      # @see http://git.io/-Wb61A have_headers_spec.rb for more examples
       def have_headers
         RSpecApi::Matchers::Headers::Matcher.new
       end