cleanup and add some rdoc

README.md

@@ -2,22 +2,7 @@
 
 rspec-2 for rails-3 with lightweight extensions to each
 
-[![build status](https://secure.travis-ci.org/rspec/rspec-rails.png)](http://travis-ci.org/rspec/rspec-rails)
-
-NOTE: rspec-2 does _not_ support rails-2. Use rspec-rails-1.3.x for rails-2.
-
-## Documentation
-
-The [Cucumber features](http://relishapp.com/rspec/rspec-rails) are the
-most comprehensive and up-to-date docs for end-users.
-
-The [RDoc](http://rubydoc.info/gems/rspec-rails/2.4.0/frames) provides additional
-information for contributors and/or extenders.
-
-All of the documentation is open source and a work in progress. If you find it
-lacking or confusing, you can help improve it by submitting requests and
-patches to the [rspec-rails issue
-tracker](https://github.com/rspec/rspec-rails/issues).
+NOTE: Use rspec-rails-1.3.x for rails-2.
 
 ## Install
 
@@ -31,7 +16,7 @@ This installs the following gems:
     rspec-mocks
     rspec-rails
 
-## Configure:
+## Configure
 
 Add `rspec-rails` to the `:test` and `:development` groups in the Gemfile:
 
@@ -44,7 +29,7 @@ tasks without having to type `RAILS_ENV=test`.
 
 Now you can run:
 
-    rails g rspec:install
+    rails generate rspec:install
 
 This adds the spec directory and some skeleton files, including
 the "rake spec" task.
@@ -56,17 +41,17 @@ see is `rspec:install`. That's because RSpec is registered with Rails as the
 test framework, so whenever you generate application components like models,
 controllers, etc, RSpec specs are generated instead of Test::Unit tests.
 
-Note that the generators are there to help you get started, but they are no
-substitute for writing your own examples, and they are only guaranteed to work
-out of the box for the default scenario (`ActiveRecord` + `Webrat`).
+Please note that the generators are there to help you get started, but they are
+no substitute for writing your own examples, and they are only guaranteed to
+work out of the box for the default scenario (`ActiveRecord` + `Webrat`).
 
 ### Autotest
 
-The `rspec:install` generator creates an `.rspec` file, which
-tells Autotest that you're using RSpec and Rails. You'll also need to add the
-autotest (not autotest-rails) gem to your Gemfile:
+The `rspec:install` generator creates an `.rspec` file, which tells Autotest
+that you're using RSpec and Rails. You'll also need to add the ZenTest gem to
+your Gemfile:
 
-    gem "autotest"
+    gem "ZenTest"
 
 At this point, if all of the gems in your Gemfile are installed in system
 gems, you can just type `autotest`. If, however, Bundler is managing any gems
@@ -82,8 +67,6 @@ your preference to the Gemfile:
     gem "webrat"
     gem "capybara"
 
-Note that Capybara matchers are not available in view or helper specs.
-
 ## Living on edge
 
 Bundler makes it a snap to use the latest code for any gem your app depends on. For

lib/generators/rspec.rb

@@ -2,7 +2,7 @@
 
 module Rspec
   module Generators
-    class Base < Rails::Generators::NamedBase #:nodoc:
+    class Base < Rails::Generators::NamedBase
       def self.source_root
         @_rspec_source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'rspec', generator_name, 'templates'))
       end
@@ -12,7 +12,7 @@ def self.source_root
 
 module Rails
   module Generators
-    class GeneratedAttribute #:nodoc:
+    class GeneratedAttribute
       def input_type
         @input_type ||= if type == :text
           "textarea"

lib/rspec/rails/example/view_example_group.rb

@@ -40,14 +40,13 @@ def _default_helpers
     end
 
     module InstanceMethods
-      # :call-seq:
-      #   render
-      #   render(:template => "widgets/new.html.erb")
-      #   render({:partial => "widgets/widget.html.erb"}, {... locals ...})
-      #   render({:partial => "widgets/widget.html.erb"}, {... locals ...}) do ... end
+      # @overload render
+      # @overload render({:partial => path_to_file})
+      # @overload render({:partial => path_to_file}, {... locals ...})
+      # @overload render({:partial => path_to_file}, {... locals ...}) do ... end
       #
-      # Delegates to ActionView::Base#render, so see documentation on that for more
-      # info.
+      # Delegates to ActionView::Base#render, so see documentation on that
+      # for more info.
       #
       # The only addition is that you can call render with no arguments, and RSpec
       # will pass the top level description to render:
@@ -63,9 +62,8 @@ def render(options={}, local_assigns={}, &block)
         super(options, local_assigns, &block)
       end
 
-      # The instance of ActionView::Base that is used to render the template.
-      # Use this before the +render+ call to stub any methods you want to stub
-      # on the view:
+      # The instance of +ActionView::Base+ that is used to render the template.
+      # Use this to stub methods _before_ calling +render+.
       #
       #   describe "widgets/new.html.erb" do
       #     it "shows all the widgets" do
@@ -98,13 +96,13 @@ def params
         controller.params
       end
 
-      # Deprecated. Use +view+ instead.
+      # @deprecated # use +view+ instead.
       def template
         RSpec.deprecate("template","view")
         view
       end
 
-      # Deprecated. Use +rendered+ instead.
+      # @deprecated # use +rendered+ instead.
       def response
         RSpec.deprecate("response", "rendered")
         rendered

lib/rspec/rails/extensions/active_record/base.rb

@@ -3,19 +3,19 @@ module Rails
     if defined?(ActiveRecord)
       module Extensions
         module ActiveRecord
-          # :call-seq:
+          # Extension to enhance +should have+ on AR Model classes
+          #
+          # == Examples
           #   ModelClass.should have(:no).records
           #   ModelClass.should have(1).record
           #   ModelClass.should have(n).records
-          #
-          # Extension to enhance <tt>should have</tt> on AR Model classes
           def records
             find(:all)
           end
           alias :record :records
         end
 
-        class ::ActiveRecord::Base #:nodoc:
+        class ::ActiveRecord::Base
           extend RSpec::Rails::Extensions::ActiveRecord
         end
       end
@@ -24,14 +24,16 @@ class ::ActiveRecord::Base #:nodoc:
 end
 
 module ::ActiveModel::Validations
-  # :call-seq:
+  # Extension to enhance <tt>should have</tt> on AR Model instances.
+  # Calls model.valid? in order to prepare the object's errors
+  # object.
+  #
+  # == Examples
+  #
   #   model.should have(:no).errors_on(:attribute)
   #   model.should have(1).error_on(:attribute)
   #   model.should have(n).errors_on(:attribute)
   #
-  # Extension to enhance <tt>should have</tt> on AR Model instances.
-  # Calls model.valid? in order to prepare the object's errors
-  # object.
   def errors_on(attribute)
     self.valid?
     [self.errors[attribute]].flatten.compact

lib/rspec/rails/matchers/have_extension.rb

@@ -1,9 +1,9 @@
 require 'active_support/core_ext/module/aliasing'
 require 'rspec/matchers/have'
 
-module RSpec #:nodoc:
-  module Matchers #:nodoc:
-    class Have #:nodoc:
+module RSpec
+  module Matchers
+    class Have
       def failure_message_for_should_with_errors_on_extensions
         return "expected #{relativities[@relativity]}#{@expected} errors on :#{@args[0]}, got #{@actual}" if @collection_name == :errors_on
         return "expected #{relativities[@relativity]}#{@expected} error on :#{@args[0]}, got #{@actual}"  if @collection_name == :error_on

lib/rspec/rails/mocks.rb

@@ -9,31 +9,39 @@ class IllegalDataAccessException < StandardError; end
     module Mocks
 
       module ActiveModelInstanceMethods
+        # Stubs +persisted?+ to return false and +id+ to return nil
+        # @return self
         def as_new_record
           self.stub(:persisted?) { false }
           self.stub(:id) { nil }
           self
         end
 
+        # Returns true by default. Override with a stub.
         def persisted?
           true
         end
 
+        # Returns false for names matching <tt>/_before_type_cast$/</tt>,
+        # otherwise delegates to super.
         def respond_to?(message, include_private=false)
           message.to_s =~ /_before_type_cast$/ ? false : super
         end
       end
 
       module ActiveRecordInstanceMethods
+        # Stubs +persisted?+ to return +false+ and +id+ to return +nil+.
         def destroy
           self.stub(:persisted?) { false }
           self.stub(:id) { nil }
         end
 
+        # Transforms the key to a method and calls it.
         def [](key)
           send(key)
         end
 
+        # Returns the opposite of +persisted?+
         def new_record?
           !persisted?
         end
@@ -129,37 +137,38 @@ def @object.to_s
       end
 
       module ActiveModelStubExtensions
+        # Stubs +persisted+ to return false and +id+ to return nil
         def as_new_record
           self.stub(:persisted?)  { false }
           self.stub(:id)          { nil }
           self
         end
 
+        # Returns +true+ by default. Override with a stub.
         def persisted?
           true
         end
       end
 
       module ActiveRecordStubExtensions
+        # Stubs +id+ (or other primary key method) to return nil
         def as_new_record
           self.__send__("#{self.class.primary_key}=", nil)
           super
         end
 
+        # Returns the opposite of +persisted?+.
         def new_record?
           !persisted?
         end
 
+        # Raises an IllegalDataAccessException (stubbed models are not allowed to access the database)
+        # @raises IllegalDataAccessException
         def connection
           raise RSpec::Rails::IllegalDataAccessException.new("stubbed models are not allowed to access the database")
         end
       end
 
-      # :call-seq:
-      #   stub_model(Model)
-      #   stub_model(Model).as_new_record
-      #   stub_model(Model, hash_of_stubs)
-      #
       # Creates an instance of +Model+ with +to_param+ stubbed using a
       # generated value that is unique to each object.. If +Model+ is an
       # +ActiveRecord+ model, it is prohibited from accessing the database*.

lib/rspec/rails/version.rb

@@ -1,6 +1,6 @@
-module RSpec # :nodoc:
-  module Rails # :nodoc:
-    module Version # :nodoc:
+module RSpec
+  module Rails
+    module Version
       STRING = '2.7.0.rc1'
     end
   end

lib/rspec/rails/view_assigns.rb

@@ -4,11 +4,12 @@ module ViewAssigns
       extend ActiveSupport::Concern
 
       module InstanceMethods
-        # :call-seq:
-        #   assign(:widget, stub_model(Widget))
-        #
         # Assigns a value to an instance variable in the scope of the
         # view being rendered.
+        #
+        # == Examples
+        #
+        #   assign(:widget, stub_model(Widget))
         def assign(key, value)
           _encapsulated_assigns[key] = value
         end