more README

README.md

@@ -1,18 +1,147 @@
 # rspec-core
 
-rspec-core provides the structure for writing executable examples of how your
-code should behave.
+rspec-core provides the structure for writing executable examples of how
+your code should behave.  It uses the words "describe" and "it" so we can
+express concepts like a conversation:
+
+    "Describe an order."
+    "It sums the prices of its line items."
+
+## basic structure
+
+    describe Order do
+      it "sums the prices of its line items" do
+        order = Order.new
+        order.add_entry(LineItem.new(:item => Item.new(
+          :price => Money.new(1.11, :USD)
+        )
+        order.add_entry(LineItem.new(:item => Item.new(
+          :price => Money.new(2.22, :USD),
+          :quantity => 2
+        )
+        order.total.should eq(Money.new(5.55, :USD))
+      end
+    end
 
-## Install
+The `describe` method creates an [ExampleGroup](../RSpec/Core/ExampleGroup).  Within the
+block passed to `describe` you can declare examples using the `it` method.
 
-    gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
-    gem install rspec-core # for rspec-core only
+Under the hood, an example group is a class in which the block passed to
+`describe` is evaluated. The blocks passed to `it` are evaluated in the
+context of an _instance_ of that class.
+
+## nested groups
+
+You can also declare nested nested groups using the `describe` or `context`
+methods:
+
+    describe Order to
+      context "with no items" do
+        it "behaves one way" do
+          # ...
+        end
+      end
+
+      context "with one item" do
+        it "behaves another way" do
+          # ...
+        end
+      end
+    end
+
+## aliases
+
+You can declare example groups using either `describe` or `context`, though
+only `describe` is available at the top level.
+
+You can declare examples within a group using any of `it`, `specify`, or
+`example`.
 
-## Upgrading from rspec-1.x
+## shared examples and contexts
 
-See [features/Upgrade.md](http://github.com/rspec/rspec-core/blob/master/features/Upgrade.md)
+Declare a shared example group using `shared_examples`, and then include it
+in any group using `include_examples`.
 
-## Get Started
+    shared_examples "collections" do |collection_class|
+      it "is empty when first created" do
+        collection_class.new.should be_empty
+      end
+    end
+
+    describe Array do
+      include_examples "collections", Array
+    end
+
+    describe Hash do
+      include_examples "collections", Hash
+    end
+
+Nearly anything that can be declared within an example group can be declared
+within a shared example group. This includes `before`, `after`, and `around`
+hooks, `let` declarations, and nested groups/contexts.
+
+You can also use the names `shared_context` and `include_context`. These are
+pretty much the same as `shared_examples` and `include_examples`, providing
+more accurate naming for in which you share hooks, `let` declarations, helper
+methods, etc, but no examples.
+
+## metadata
+
+rspec-core stores a metadata hash with every example and group, which
+contains like their descriptions, the locations at which they were
+declared, etc, etc. This hash powers many of rspec-core's features,
+including output formatters (which access descriptions and locations),
+and filtering before and after hooks.
+
+Although you probably won't ever need this unless you are writing an
+extension, you can access it from an example like this:
+
+    it "does something" do
+      example.metadata[:description].should eq("does something")
+    end
+
+### `described_class`
+
+When a class is passed to `describe`, you can access it from an example
+using the `described_class` method, which is a wrapper for
+`example.metadata[:described_class]`.
+
+    describe Widget do
+      example do
+        described_class.should equal(Widget)
+      end
+    end
+
+This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the shared examples example from above, we can
+clean it up a bit using `described_class`:
+
+    shared_examples "collections" do
+      it "is empty when first created" do
+        described.new.should be_empty
+      end
+    end
+
+    describe Array do
+      include_examples "collections"
+    end
+
+    describe Hash do
+      include_examples "collections"
+    end
+
+## the `rspec` command
+
+When you install the rspec-core gem, it installs the `rspec` executable,
+which you'll use to run rspec. The `rspec` comes with many useful options.
+Run `rspec --help` to see the complete list.
+## 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)
+
+## get started
 
 Start with a simple example of behavior you expect from your system. Do
 this before you write any implementation code:
@@ -61,8 +190,8 @@ Use the `documentation` formatter to see the resulting spec:
     Finished in 0.000379 seconds
     1 example, 0 failures
 
-## See also
+## install
+
+    gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
+    gem install rspec-core # for rspec-core only
 
-* [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/rspec/core.rb

@@ -87,128 +87,6 @@ def self.clear_remaining_example_groups
     world.example_groups.clear
   end
 
-  # rspec-core provides the structure for writing executable examples of how
-  # your code should behave.  It uses the words "describe" and "it" so we can
-  # express concepts like a conversation:
-  #
-  #     "Describe an order."
-  #     "It sums the prices of its line items."
-  #
-  # ## Basic structure
-  #
-  #     describe Order do
-  #       it "sums the prices of its line items" do
-  #         order = Order.new
-  #         order.add_entry(LineItem.new(:item => Item.new(
-  #           :price => Money.new(1.11, :USD)
-  #         )
-  #         order.add_entry(LineItem.new(:item => Item.new(
-  #           :price => Money.new(2.22, :USD),
-  #           :quantity => 2
-  #         )
-  #         order.total.should eq(Money.new(5.55, :USD))
-  #       end
-  #     end
-  #
-  # The `describe` method creates an [ExampleGroup](Core/ExampleGroup).  Within the
-  # block passed to `describe` you can declare examples using the `it` method.
-  #
-  # Under the hood, an example group is a class in which the block passed to
-  # `describe` is evaluated. The blocks passed to `it` are evaluated in the
-  # context of an _instance_ of that class.
-  #
-  # ## Nested groups
-  #
-  # You can also declare nested nested groups using the `describe` or `context`
-  # methods:
-  #
-  #     describe Order to
-  #       context "with no items" do
-  #         it "behaves one way" do
-  #           # ...
-  #         end
-  #       end
-  #
-  #       context "with one item" do
-  #         it "behaves another way" do
-  #           # ...
-  #         end
-  #       end
-  #     end
-  #
-  # ## Aliases
-  #
-  # You can declare example groups using either `describe` or `context`, though
-  # only `describe` is available at the top level.
-  #
-  # You can declare examples within a group using any of `it`, `specify`, or
-  # `example`.
-  #
-  # ## Shared examples
-  #
-  # Declare a shared example group using `shared_examples`, and then include it
-  # in each group using `include_examples`.
-  #
-  #     shared_examples "collections" do |collection_class|
-  #       it "is empty when first created" do
-  #         collection_class.new.should be_empty
-  #       end
-  #     end
-  #
-  #     describe Array do
-  #       include_examples "collections", Array
-  #     end
-  #
-  # ## Metadata
-  #
-  # rspec-core stores a metadata hash with every example and group, which
-  # contains like their descriptions, the locations at which they were
-  # declared, etc, etc. This hash powers many of rspec-core's features,
-  # including output formatters (which access descriptions and locations),
-  # and filtering before and after hooks.
-  #
-  # Although you probably won't ever need this unless you are writing an
-  # extension, you can access it from an example like this:
-  #
-  #     it "does something" do
-  #       example.metadata[:description].should eq("does something")
-  #     end
-  #
-  # ### `described_class`
-  #
-  # When a class is passed to `describe`, you can access it from an example
-  # using the `described_class` method, which is a wrapper for
-  # `example.metadata[:described_class]`.
-  #
-  #     describe Widget do
-  #       example do
-  #         described_class.should equal(Widget)
-  #       end
-  #     end
-  #
-  # This is useful in extensions or shared example groups in which the specific
-  # class is unknown. Taking the shared examples example from above, we can
-  # clean it up a bit using `described_class`:
-  #
-  #     shared_examples "collections" do
-  #       it "is empty when first created" do
-  #         described.new.should be_empty
-  #       end
-  #     end
-  #
-  #     describe Array do
-  #       include_examples "collections"
-  #     end
-  #
-  #     describe Hash do
-  #       include_examples "collections"
-  #     end
-  #
-  # ## The `rspec` command
-  #
-  # When you install the rspec-core gem, it installs the `rspec` executable,
-  # which you'll use to run rspec. The `rspec` comes with many useful options.
-  # Run `rspec --help` to see the complete list.
   module Core
   end
 end

lib/rspec/core/example_group.rb

@@ -98,10 +98,16 @@ class << self
 
       alias_it_should_behave_like_to :it_behaves_like, "behaves like"
 
+      # Includes shared content declared with `name`.
+      #
+      # @see SharedExampleGroup
       def self.include_context(name)
         module_eval(&find_shared("context", name))
       end
 
+      # Includes shared content declared with `name`.
+      #
+      # @see SharedExampleGroup
       def self.include_examples(name)
         module_eval(&find_shared("examples", name))
       end

lib/rspec/core/shared_example_group.rb

@@ -2,7 +2,14 @@ module RSpec
   module Core
     module SharedExampleGroup
 
-      def shared_context(*args, &block)
+      # @overload shared_examples(name, &block)
+      # @overload shared_examples(name, tags, &block)
+      #
+      # Creates and stores (but does not evaluate) the block.
+      #
+      # @see ExampleGroup.include_examples
+      # @see ExampleGroup.include_context
+      def shared_examples(*args, &block)
         if [String, Symbol, Module].any? {|cls| cls === args.first }
           object = args.shift
           ensure_shared_example_group_name_not_taken(object)
@@ -18,9 +25,9 @@ def shared_context(*args, &block)
         end
       end
 
-      alias :shared_examples     :shared_context
-      alias :share_examples_for  :shared_context
-      alias :shared_examples_for :shared_context
+      alias_method :shared_context,      :shared_examples
+      alias_method :share_examples_for,  :shared_examples
+      alias_method :shared_examples_for, :shared_examples
 
       def share_as(name, &block)
         if Object.const_defined?(name)
@@ -46,7 +53,6 @@ def self.included(kls)
         RSpec.world.shared_example_groups[shared_const] = block
       end
 
-
     private
 
       def raise_name_error