diff --git a/.yardopts b/.yardopts
index 816e5a34a7..372dbf2edb 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,5 +1,6 @@
 --no-private
 --exclude features
 --exclude lib/generators/**/*_spec.rb
+--markup markdown
 -
 README.md
diff --git a/Rakefile b/Rakefile
index ce6d22ae19..301abb69ec 100644
--- a/Rakefile
+++ b/Rakefile
@@ -123,6 +123,8 @@ desc 'clobber generated files'
 task :clobber do
   rm_rf "pkg"
   rm_rf "tmp"
+  rm_rf "doc"
+  rm_rf ".yardoc"
   rm    "Gemfile.lock" if File.exist?("Gemfile.lock")
 end
 
diff --git a/lib/rspec/rails/example/controller_example_group.rb b/lib/rspec/rails/example/controller_example_group.rb
index 2b98246f5f..6ee1f55189 100644
--- a/lib/rspec/rails/example/controller_example_group.rb
+++ b/lib/rspec/rails/example/controller_example_group.rb
@@ -3,24 +3,29 @@
 end
 
 module RSpec::Rails
-  # Extends ActionController::TestCase::Behavior to work with RSpec.
+  # Extends ActionController::TestCase::Behavior to work with RSpec, with
+  # some caveats.
   #
-  # == Examples
+  # rspec-rails is designed to support separate specs for models, controllers,
+  # views (where appropriate) and helpers. Rails allows this separation, but
+  # discourages real isolation by rendering views in controller tests
   #
-  # == with stubs
+  # ## Examples
+  #
+  # ### with fixtures
   #
   #   describe WidgetsController do
   #     describe "GET index" do
+  #       fixtures :widgets
+  #
   #       it "assigns all widgets to @widgets" do
-  #         widget = stub_model(Widget)
-  #         Widget.stub(:all) { widget }
   #         get :index
-  #         assigns(:widgets).should eq([widget])
+  #         assigns(:widgets).should eq(Widget.all)
   #       end
   #     end
   #   end
   #
-  # === with a factory
+  # ### with a factory
   #
   #   describe WidgetsController do
   #     describe "GET index" do
@@ -32,31 +37,31 @@ module RSpec::Rails
   #     end
   #   end
   #
-  # === with fixtures
+  # ## with stubs
   #
   #   describe WidgetsController do
   #     describe "GET index" do
-  #       fixtures :widgets
-  #
   #       it "assigns all widgets to @widgets" do
+  #         widget = stub_model(Widget)
+  #         Widget.stub(:all) { widget }
   #         get :index
-  #         assigns(:widgets).should eq(Widget.all)
+  #         assigns(:widgets).should eq([widget])
   #       end
   #     end
   #   end
   #
-  # == Matchers
+  # ## Matchers
   #
   # In addition to the stock matchers from rspec-expectations, controller
   # specs add these matchers, which delegate to rails' assertions:
   #
-  #   response.should render_template(*args)
-  #   => delegates to assert_template(*args)
+  #     response.should render_template(*args)
+  #     # => delegates to assert_template(*args)
   #
-  #   response.should redirect_to(destination)
-  #   => delegates to assert_redirected_to(destination)
+  #     response.should redirect_to(destination)
+  #     # => delegates to assert_redirected_to(destination)
   #
-  # == Isolation from views
+  # ## Isolation from views
   #
   # RSpec's preferred approach to spec'ing controller behaviour is to isolate
   # the controller from its collaborators.  By default, therefore, controller
@@ -68,7 +73,7 @@ module RSpec::Rails
   # require the presence of the file at all. Due to changes in rails-3, this
   # was no longer feasible in rspec-rails-2.
   #
-  # == View rendering
+  # ## View rendering
   #
   # If you prefer a more integrated approach, similar to that of Rails'
   # functional tests, you can tell controller groups to render the views in the
@@ -88,6 +93,7 @@ module ControllerExampleGroup
     include RSpec::Rails::Matchers::RoutingMatchers
 
     module ClassMethods
+      # @api private
       def controller_class
         describes
       end
@@ -98,7 +104,7 @@ def controller_class
       # up implicit routes for this controller, that are separate from those
       # defined in <tt>config/routes.rb</tt>.
       #
-      # == Examples
+      # ## Examples
       #
       #    describe ApplicationController do
       #      controller do
@@ -158,10 +164,16 @@ def rescue_with_handler(exception)
         end
       end
 
+      # Extends the controller with a module that overrides
+      # `rescue_with_handler` to raise the exception passed to it.  Use this to
+      # specify that an action _should_ raise an exception given appropriate
+      # conditions.
       def bypass_rescue
         controller.extend(BypassRescue)
       end
 
+      # If method is a named_route, delegates to the RouteSet associated with
+      # this controller.
       def method_missing(method, *args, &block)
         if @orig_routes && @orig_routes.named_routes.helpers.include?(method)
           controller.send(method, *args, &block)