Add documentation for how spec files are required/run.

Closes 623.

Signed-off-by: Sam Phippen <samphippen@googlemail.com>

README.md

@@ -28,6 +28,11 @@ Initialize the `spec/` directory (where specs will reside) with:
 rails generate rspec:install
 ```
 
+This adds the spec directory and some skeleton files, including the "rake spec"
+task. Any ruby file in `spec/support` will be included with `require`. All
+files in spec/ and subdirectories that end with `_spec.rb` will be run as
+specs.
+
 To run your specs, use the `rspec` command:
 
 ```

lib/generators/rspec/install/templates/spec/spec_helper.rb.tt

@@ -5,7 +5,11 @@ require 'rspec/rails'
 require 'rspec/autorun'
 
 # Requires supporting ruby files with custom matchers and macros, etc,
-# in spec/support/ and its subdirectories.
+# in spec/support/ and its subdirectories. Files matching `spec/**/*_spec.rb`
+# are run as spec files by default. This means that files in spec/support that
+# end in _spec.rb will both be required and run as specs, causing the specs
+# to be run twice. It is recommended that you do not name files matching
+# this glob to end with _spec.rb.
 Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }
 
 <% if ::Rails::VERSION::STRING >= '4' -%>