Extract examples in README to inline documentation

lib/shoulda/matchers/action_controller.rb

@@ -13,26 +13,6 @@
 
 module Shoulda
   module Matchers
-    # By using the matchers you can quickly and easily create concise and
-    # easy to read test suites.
-    #
-    # This code segment:
-    #
-    #   describe UsersController, 'on GET to show with a valid id' do
-    #     before(:each) do
-    #       get :show, id: User.first.to_param
-    #     end
-    #
-    #     it { should respond_with(:success) }
-    #     it { should render_template(:show) }
-    #     it { should not_set_the_flash) }
-    #
-    #     it 'does something else really cool' do
-    #       expect(assigns[:user].id).to eq 1
-    #     end
-    #   end
-    #
-    # Would produce 5 tests for the show action
     module ActionController
     end
   end

lib/shoulda/matchers/action_controller/callback_matcher.rb

@@ -1,67 +1,158 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-      # Ensure a controller uses a given before_filter
+    module ActionController
+      # The `use_before_filter` matcher is used to test that a before_filter
+      # callback is defined within your controller.
       #
-      # Example:
+      #     class UsersController < ApplicationController
+      #       before_filter :authenticate_user!
+      #     end
+      #
+      #     # RSpec
+      #     describe UsersController do
+      #       it { should use_before_filter(:authenticate_user!) }
+      #       it { should_not use_before_filter(:prevent_ssl) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class UsersControllerTest < ActionController::TestCase
+      #       should use_before_filter(:authenticate_user!)
+      #       should_not use_before_filter(:prevent_ssl)
+      #     end
+      #
+      # @return [CallbackMatcher]
       #
-      #   it { should use_before_filter(:authenticate_user!) }
-      #   it { should_not use_before_filter(:prevent_ssl) }
       def use_before_filter(callback)
         CallbackMatcher.new(callback, :before, :filter)
       end
 
-      # Ensure a controller uses a given before_filter
+      # The `use_after_filter` matcher is used to test that an after_filter
+      # callback is defined within your controller.
+      #
+      #     class IssuesController < ApplicationController
+      #       after_filter :log_activity
+      #     end
+      #
+      #     # RSpec
+      #     describe IssuesController do
+      #       it { should use_after_filter(:log_activity) }
+      #       it { should_not use_after_filter(:destroy_user) }
+      #     end
       #
-      # Example:
+      #     # Test::Unit
+      #     class IssuesControllerTest < ActionController::TestCase
+      #       should use_after_filter(:log_activity)
+      #       should_not use_after_filter(:destroy_user)
+      #     end
+      #
+      # @return [CallbackMatcher]
       #
-      #   it { should use_after_filter(:log_activity) }
-      #   it { should_not use_after_filter(:destroy_user) }
       def use_after_filter(callback)
         CallbackMatcher.new(callback, :after, :filter)
       end
 
-      # Ensure a controller uses a given before_action
+      # The `use_before_action` matcher is used to test that a before_action
+      # callback is defined within your controller.
+      #
+      #     class UsersController < ApplicationController
+      #       before_action :authenticate_user!
+      #     end
+      #
+      #     # RSpec
+      #     describe UsersController do
+      #       it { should use_before_action(:authenticate_user!) }
+      #       it { should_not use_before_action(:prevent_ssl) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class UsersControllerTest < ActionController::TestCase
+      #       should use_before_action(:authenticate_user!)
+      #       should_not use_before_action(:prevent_ssl)
+      #     end
       #
-      # Example:
+      # @return [CallbackMatcher]
       #
-      #   it { should use_before_action(:authenticate_user!) }
-      #   it { should_not use_before_action(:prevent_ssl) }
       def use_before_action(callback)
         CallbackMatcher.new(callback, :before, :action)
       end
 
-      # Ensure a controller uses a given after_action
+      # The `use_after_action` matcher is used to test that an after_action
+      # callback is defined within your controller.
       #
-      # Example:
+      #     class IssuesController < ApplicationController
+      #       after_action :log_activity
+      #     end
+      #
+      #     # RSpec
+      #     describe IssuesController do
+      #       it { should use_after_action(:log_activity) }
+      #       it { should_not use_after_action(:destroy_user) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class IssuesControllerTest < ActionController::TestCase
+      #       should use_after_action(:log_activity)
+      #       should_not use_after_action(:destroy_user)
+      #     end
+      #
+      # @return [CallbackMatcher]
       #
-      #   it { should use_after_action(:log_activity) }
-      #   it { should_not use_after_action(:destroy_user) }
       def use_after_action(callback)
         CallbackMatcher.new(callback, :after, :action)
       end
 
-      # Ensure a controller uses a given around_filter
+      # The `use_around_filter` matcher is used to test that an around_filter
+      # callback is defined within your controller.
+      #
+      #     class ChangesController < ApplicationController
+      #       around_filter :wrap_in_transaction
+      #     end
+      #
+      #     # RSpec
+      #     describe ChangesController do
+      #       it { should use_around_filter(:wrap_in_transaction) }
+      #       it { should_not use_around_filter(:save_view_context) }
+      #     end
       #
-      # Example:
+      #     # Test::Unit
+      #     class ChangesControllerTest < ActionController::TestCase
+      #       should use_around_filter(:wrap_in_transaction)
+      #       should_not use_around_filter(:save_view_context)
+      #     end
+      #
+      # @return [CallbackMatcher]
       #
-      #   it { should use_around_filter(:log_activity) }
-      #   it { should_not use_around_filter(:destroy_user) }
       def use_around_filter(callback)
         CallbackMatcher.new(callback, :around, :filter)
       end
 
-      # Ensure a controller uses a given around_action
+      # The `use_around_action` matcher is used to test that an around_action
+      # callback is defined within your controller.
+      #
+      #     class ChangesController < ApplicationController
+      #       around_action :wrap_in_transaction
+      #     end
+      #
+      #     # RSpec
+      #     describe ChangesController do
+      #       it { should use_around_action(:wrap_in_transaction) }
+      #       it { should_not use_around_action(:save_view_context) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class ChangesControllerTest < ActionController::TestCase
+      #       should use_around_action(:wrap_in_transaction)
+      #       should_not use_around_action(:save_view_context)
+      #     end
       #
-      # Example:
+      # @return [CallbackMatcher]
       #
-      #   it { should use_around_action(:log_activity) }
-      #   it { should_not use_around_action(:destroy_user) }
       def use_around_action(callback)
         CallbackMatcher.new(callback, :around, :action)
       end
 
-      class CallbackMatcher # :nodoc:
+      # @private
+      class CallbackMatcher
         def initialize(method_name, kind, callback_type)
           @method_name = method_name
           @kind = kind

lib/shoulda/matchers/action_controller/filter_param_matcher.rb

@@ -1,16 +1,32 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-      # Ensures that filter_parameter_logging is set for the specified key.
+    module ActionController
+      # The `filter_param` matcher is used to test parameter filtering
+      # configuration. Specifically, it asserts that the given parameter is
+      # present in `config.filter_parameters`.
       #
-      # Example:
+      #     class MyApplication < Rails::Application
+      #       config.filter_parameters << :secret_key
+      #     end
+      #
+      #     # RSpec
+      #     describe ApplicationController do
+      #       it { should filter_param(:secret_key) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class ApplicationControllerTest < ActionController::TestCase
+      #       should filter_param(:secret_key)
+      #     end
+      #
+      # @return [FilterParamMatcher]
       #
-      #   it { should filter_param(:password) }
       def filter_param(key)
         FilterParamMatcher.new(key)
       end
 
-      class FilterParamMatcher # :nodoc:
+      # @private
+      class FilterParamMatcher
         def initialize(key)
           @key = key.to_s
         end

lib/shoulda/matchers/action_controller/redirect_to_matcher.rb

@@ -1,17 +1,46 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-      # Ensures a controller redirected to the given url.
+    module ActionController
+      # The `redirect_to` matcher tests that an action redirects to a certain
+      # location. In a test suite using RSpec, it is very similar to
+      # rspec-rails's `redirect_to` matcher. In a test suite using Test::Unit /
+      # Shoulda, it provides a more expressive syntax over
+      # `assert_redirected_to`.
       #
-      # Example:
+      #     class PostsController < ApplicationController
+      #       def show
+      #         redirect_to :index
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
+      #
+      #         it { should redirect_to(posts_path) }
+      #         it { should redirect_to(action: :index) }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should redirect_to { posts_path }
+      #         should redirect_to(action: :index)
+      #       end
+      #     end
+      #
+      # @return [RedirectToMatcher]
       #
-      #   it { should redirect_to('http://somewhere.com')  }
-      #   it { should redirect_to(users_path)  }
       def redirect_to(url_or_description, &block)
         RedirectToMatcher.new(url_or_description, self, &block)
       end
 
-      class RedirectToMatcher # :nodoc:
+      # @private
+      class RedirectToMatcher
         attr_reader :failure_message, :failure_message_when_negated
 
         alias failure_message_for_should failure_message

lib/shoulda/matchers/action_controller/render_template_matcher.rb

@@ -1,25 +1,49 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-      # Ensures a controller rendered the given template.
+    module ActionController
+      # The `render_template` matcher tests that an action renders a template
+      # or partial. In RSpec, it is very similar to rspec-rails's
+      # `render_template` matcher. In Test::Unit, it provides a more expressive
+      # syntax over `assert_template`.
       #
-      # Example:
+      #     class PostsController < ApplicationController
+      #       def show
+      #       end
+      #     end
       #
-      #   it { should render_template(:show)  }
+      #     # app/views/posts/show.html.erb
+      #     <%= render 'sidebar' %>
       #
-      #   assert that the "_customer" partial was rendered
-      #   it { should render_template(partial: '_customer')  }
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
       #
-      #   assert that the "_customer" partial was rendered twice
-      #   it { should render_template(partial: '_customer', count: 2)  }
+      #         it { should render_template('show') }
+      #         it { should render_template(partial: 'sidebar') }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should render_template('show')
+      #         should render_template(partial: 'sidebar')
+      #       end
+      #     end
+      #
+      # 
+      #
+      # @return [RenderTemplateMatcher]
       #
-      #   assert that no partials were rendered
-      #   it { should render_template(partial: false)  }
       def render_template(options = {}, message = nil)
         RenderTemplateMatcher.new(options, message, self)
       end
 
-      class RenderTemplateMatcher # :nodoc:
+      # @private
+      class RenderTemplateMatcher
         attr_reader :failure_message, :failure_message_when_negated
 
         alias failure_message_for_should failure_message