--- a/rspec/lib/spec/example/configuration.rb
+++ b/rspec/lib/spec/example/configuration.rb
@@ -7,14 +7,20 @@ module Spec
       #     config.mock_with :rspec, :mocha, :flexmock, or :rr
       #   end
       #
-      # To use any other mock framework, you'll have to provide
-      # your own adapter. This is simply a module that responds to
-      # setup_mocks_for_rspec, verify_mocks_for_rspec and teardown_mocks_for_rspec.
+      # To use any other mock framework, you'll have to provide your own
+      # adapter. This is simply a module that responds to the following
+      # methods:
+      #
+      #   setup_mocks_for_rspec
+      #   verify_mocks_for_rspec
+      #   teardown_mocks_for_rspec.
+      #
       # These are your hooks into the lifecycle of a given example. RSpec will
-      # call setup_mocks_for_rspec before running anything else in each Example.
-      # After executing the #after methods, RSpec will then call verify_mocks_for_rspec
-      # and teardown_mocks_for_rspec (this is guaranteed to run even if there are
-      # failures in verify_mocks_for_rspec).
+      # call setup_mocks_for_rspec before running anything else in each
+      # Example. After executing the #after methods, RSpec will then call
+      # verify_mocks_for_rspec and teardown_mocks_for_rspec (this is
+      # guaranteed to run even if there are failures in
+      # verify_mocks_for_rspec).
       #
       # Once you've defined this module, you can pass that to mock_with:
       #
@@ -35,12 +41,18 @@ module Spec
         @mock_framework ||= mock_framework_path("rspec")
       end
       
-      # Declares modules to be included in all example groups (<tt>describe</tt> blocks).
-      #
-      #   config.include(My::Bottle, My::Cup)
-      #
-      # If you want to restrict the inclusion to a subset of all the example groups then
-      # specify this in a Hash as the last argument:
+      # :call-seq:
+      #   include(Some::Helpers)
+      #   include(Some::Helpers, More::Helpers)
+      #   include(My::Helpers, :type => :key)
+      #
+      # Declares modules to be included in multiple example groups
+      # (<tt>describe</tt> blocks). With no :type, the modules listed will be
+      # included in all example groups. Use :type to restrict the inclusion to
+      # a subset of example groups. The value assigned to :type should be a
+      # key that maps to a class that is either a subclass of
+      # Spec::Example::ExampleGroup or extends Spec::Example::ExampleGroupMethods
+      # and includes Spec::Example::ExampleMethods
       #
       #   config.include(My::Pony, My::Horse, :type => :farm)
       #
@@ -70,7 +82,7 @@ module Spec
       #
       # This makes it possible to say:
       #
-      #   person.should swim # passes if person.should_swim? returns true
+      #   person.should swim # passes if person.can_swim? returns true
       #
       def predicate_matchers
         @predicate_matchers ||= {}
@@ -85,10 +97,11 @@ module Spec
         )
         example_group.prepend_before(scope, &proc)
       end
+      
       # Appends a global <tt>before</tt> block to all example groups.
       #
-      # If you want to restrict the block to a subset of all the example groups then
-      # specify this in a Hash as the last argument:
+      # If you want to restrict the block to a subset of all the example
+      # groups then specify this in a Hash as the last argument:
       #
       #   config.prepend_before(:all, :type => :farm)
       #
@@ -115,6 +128,7 @@ module Spec
         example_group.prepend_after(scope, &proc)
       end
       alias_method :after, :prepend_after
+      
       # Appends a global <tt>after</tt> block to all example groups.
       # See #append_before for filtering semantics.
       def append_after(*args, &proc)

--- a/rspec/lib/spec/example/example_group.rb
+++ b/rspec/lib/spec/example/example_group.rb
@@ -1,6 +1,7 @@
 module Spec
   module Example
-    # The superclass for all regular RSpec examples.
+    # Base class for customized example groups. Use this if you
+    # want to make a custom example group.
     class ExampleGroup
       extend Spec::Example::ExampleGroupMethods
       include Spec::Example::ExampleMethods

--- a/rspec/lib/spec/example/example_group_factory.rb
+++ b/rspec/lib/spec/example/example_group_factory.rb
@@ -7,16 +7,22 @@ module Spec
           default(ExampleGroup)
         end
 
-        # Registers an example group class +klass+ with the symbol
-        # +type+. For example:
+        # Registers an example group class +klass+ with the symbol +type+. For
+        # example:
         #
-        #   Spec::Example::ExampleGroupFactory.register(:farm, Spec::Farm::Example::FarmExampleGroup)
+        #   Spec::Example::ExampleGroupFactory.register(:farm, FarmExampleGroup)
         #
-        # This will cause Main#describe from a file living in 
-        # <tt>spec/farm</tt> to create example group instances of type
-        # Spec::Farm::Example::FarmExampleGroup.
-        def register(id, example_group_class)
-          @example_group_types[id] = example_group_class
+        # With that you can append a hash with :type => :farm to the describe
+        # method and it will load an instance of FarmExampleGroup.
+        #
+        #   describe Pig, :type => :farm do
+        #     ...
+        #
+        # If you don't use the hash explicitly, <tt>describe</tt> will
+        # implicitly use an instance of FarmExampleGroup for any file loaded
+        # from the <tt>./spec/farm</tt> directory.
+        def register(key, example_group_class)
+          @example_group_types[key] = example_group_class
         end
         
         # Sets the default ExampleGroup class
@@ -26,11 +32,11 @@ module Spec
           @example_group_types.merge!(old) if old
         end
 
-        def get(id=nil)
-          if @example_group_types.values.include?(id)
-            id
+        def get(key=nil)
+          if @example_group_types.values.include?(key)
+            key
           else
-            @example_group_types[id]
+            @example_group_types[key]
           end
         end
         
@@ -43,12 +49,12 @@ module Spec
         protected
 
         def determine_superclass(opts)
-          id = if opts[:type]
+          key = if opts[:type]
             opts[:type]
           elsif opts[:spec_path] =~ /spec(\\|\/)(#{@example_group_types.keys.join('|')})/
             $2 == '' ? nil : $2.to_sym
           end
-          get(id)
+          get(key)
         end
 
       end