clean up some of the generated rdoc

.yardopts

@@ -1,4 +1,4 @@
 --no-private
 --exclude features
 -
-lib/**/*.rb
+README.md

README.md

@@ -1,23 +1,8 @@
-# RSpec Core
+# rspec-core
 
 RSpec Core provides the structure for writing executable examples of how your
 code should behave.
 
-[![build status](https://secure.travis-ci.org/rspec/rspec-core.png)](http://travis-ci.org/rspec/rspec-core)
-
-## Documentation
-
-The [Cucumber features](http://relishapp.com/rspec/rspec-core) are the
-most comprehensive and up-to-date docs for end-users.
-
-The [RDoc](http://rubydoc.info/gems/rspec-core/2.3.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-core issue
-tracker](https://github.com/rspec/rspec-core/issues).
-
 ## Install
 
     gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
@@ -27,18 +12,14 @@ tracker](https://github.com/rspec/rspec-core/issues).
 
 See [features/Upgrade.md](http://github.com/rspec/rspec-core/blob/master/features/Upgrade.md)
 
-
-This will install the rspec, rspec-core, rspec-expectations and rspec-mocks
-gems.
-
 ## Get Started
 
 Start with a simple example of behavior you expect from your system. Do
 this before you write any implementation code:
 
     # in spec/calculator_spec.rb
-    describe Calculator, "add" do
-      it "returns the sum of its arguments" do
+    describe Calculator do
+      it "add(x,y) returns the sum of its arguments" do
         Calculator.new.add(1, 2).should eq(3)
       end
     end
@@ -60,8 +41,7 @@ Implement the simplest solution:
 Be sure to require the implementation file in the spec:
 
     # in spec/calculator_spec.rb
-    # - RSpec adds ./lib to the $LOAD_PATH, so you can
-    #   just require "calculator" directly
+    # - RSpec adds ./lib to the $LOAD_PATH
     require "calculator"
 
 Now run the spec again, and watch it pass:
@@ -72,7 +52,7 @@ Now run the spec again, and watch it pass:
     Finished in 0.000315 seconds
     1 example, 0 failures
 
-Use the documentation formatter to see the resulting spec:
+Use the `documentation` formatter to see the resulting spec:
 
     $ rspec spec/calculator_spec.rb --format doc
     Calculator add
@@ -81,26 +61,8 @@ Use the documentation formatter to see the resulting spec:
     Finished in 0.000379 seconds
     1 example, 0 failures
 
-## Known issues
-
-See [http://github.com/rspec/rspec-core/issues](http://github.com/rspec/rspec-core/issues)
-
-## Learn more
-
-While not comprehensive yet, you can learn quite a lot from the Cucumber
-features in the [features
-directory](http://github.com/rspec/rspec-core/tree/master/features/).  If there
-is a feature that is not documented there, or you find them insufficient to
-understand how to use a feature, please submit issues to
-[http://github.com/rspec/rspec-core/issues](http://github.com/rspec/rspec-core/issues).
-
-## Contribute
-
-See [http://github.com/rspec/rspec-dev](http://github.com/rspec/rspec-dev)
-
-## Also see
+## See also
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
 * [http://github.com/rspec/rspec-expectations](http://github.com/rspec/rspec-expectations)
 * [http://github.com/rspec/rspec-mocks](http://github.com/rspec/rspec-mocks)
-

lib/autotest/rspec2.rb

@@ -18,6 +18,7 @@ def initialize
     self.completed_re = /\n(?:\e\[\d*m)?\d* examples?/m
   end
 
+  # Adds conventional spec-to-file mappings to Autotest configuation.
   def setup_rspec_project_mappings
     add_mapping(%r%^spec/.*_spec\.rb$%) { |filename, _|
       filename
@@ -30,6 +31,7 @@ def setup_rspec_project_mappings
     }
   end
 
+  # Overrides Autotest's implementation to read rspec output
   def consolidate_failures(failed)
     filters = new_hash_of_arrays
     failed.each do |spec, trace|
@@ -40,26 +42,30 @@ def consolidate_failures(failed)
     return filters
   end
 
+  # Overrides Autotest's implementation to generate the rspec command to run
   def make_test_cmd(files_to_test)
     files_to_test.empty? ? '' :
       "#{prefix}#{ruby}#{suffix} -S #{SPEC_PROGRAM} --tty #{normalize(files_to_test).keys.flatten.map { |f| "'#{f}'"}.join(' ')}"
   end
 
+  # Generates a map of filenames to Arrays for Autotest
   def normalize(files_to_test)
     files_to_test.keys.inject({}) do |result, filename|
-      result[File.expand_path(filename)] = []
-      result
+      result.merge!(File.expand_path(filename) => [])
     end
   end
 
+  # @private
   def suffix
     using_bundler? ? "" : defined?(:Gem) ? " -rrubygems" : ""
   end
 
+  # @private
   def using_bundler?
     prefix =~ /bundle exec/
   end
 
+  # @private
   def gemfile?
     File.exist?('./Gemfile')
   end

lib/rspec/core/backward_compatibility.rb

@@ -1,6 +1,8 @@
 module RSpec
   module Core
     module ConstMissing
+      # Used to print deprecation warnings for Rspec and Spec constants (use
+      # RSpec instead)
       def const_missing(name)
         case name
         when :Rspec, :Spec
@@ -29,13 +31,16 @@ def const_missing(name)
   end
 
   module Runner
+    # @deprecated use RSpec.configure instead.
     def self.configure(&block)
       RSpec.deprecate("Spec::Runner.configure", "RSpec.configure")
       RSpec.configure(&block)
     end
   end
 
   module Rake
+    # Used to print deprecation warnings for Rake::SpecTask constant (use
+    # RSpec::Core::RakeTask instead)
     def self.const_missing(name)
       case name
       when :SpecTask

lib/rspec/core/deprecation.rb

@@ -1,6 +1,7 @@
 module RSpec
 
   class << self
+    # Used internally to print deprecation warnings
     def deprecate(method, alternate_method=nil, version=nil)
       version_string = version ? "rspec-#{version}" : "a future version of RSpec"
 
@@ -24,11 +25,13 @@ def deprecate(method, alternate_method=nil, version=nil)
       warn_deprecation(message)
     end
 
+    # Used internally to print deprecation warnings
     def warn_deprecation(message)
       send :warn, message
     end
   end
 
+  # @private
   class HashWithDeprecationNotice < Hash
 
     def initialize(method, alternate_method=nil)

lib/rspec/core/extensions/kernel.rb

@@ -1,5 +1,9 @@
 module Kernel
-  def debugger(*args)
-    (RSpec.configuration.error_stream || $stderr).puts "\n***** debugger statement ignored, use -d or --debug option to enable debugging\n#{caller(0)[1]}"
-  end unless respond_to?(:debugger)
+  unless respond_to?(:debugger)
+    # If not already defined by ruby-debug, this implementation prints helpful
+    # message to STDERR when ruby-debug is not loaded.
+    def debugger(*args)
+      (RSpec.configuration.error_stream || $stderr).puts "\n***** debugger statement ignored, use -d or --debug option to enable debugging\n#{caller(0)[1]}"
+    end 
+  end
 end