Allow to use markdown in yard docs and write better documentation for session's reset method

Gemfile

@@ -4,3 +4,7 @@ gem 'bundler', '~> 1.1'
 gemspec
 
 gem 'xpath', :git => 'git://github.com/jnicklas/xpath.git'
+
+group :doc do
+  gem 'redcarpet', :platforms => :mri
+end

Rakefile

@@ -17,7 +17,7 @@ end
 
 YARD::Rake::YardocTask.new do |t|
   t.files   = ['lib/**/*.rb']
-  #t.options = ['--any', '--extra', '--opts'] # optional
+  t.options = %w(--markup=markdown)
 end
 
 Cucumber::Rake::Task.new(:cucumber) do |task|

gemfiles/Gemfile.base-versions

@@ -9,7 +9,6 @@ gem 'rack', '= 1.3.0' # cannot go lower because referer tests need aa7ce77cd0
 gem 'rack-test', '= 0.5.4'
 gem 'nokogiri', '= 1.3.3'
 gem 'rspec', '= 2.2.0'
-gem 'fuubar', '>= 0.0.1'
 gem 'cucumber', '= 0.10.5'
 # We cannot test against older versions of selenium-webdriver without
 # installing older compatible Firefox versions.

lib/capybara/session.rb

@@ -73,7 +73,21 @@ module Capybara
 
     ##
     #
-    # Reset the session, removing all cookies.
+    # Reset the session (i.e. remove cookies and navigate to blank page)
+    #
+    # This method does not:
+    #
+    #   * accept modal dialogs if they are present
+    #   * clear browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc.
+    #   * modify state of the driver/underlying browser in any other way
+    #
+    # as doing so will result in performance downsides and it's not needed to do everything from the list above for most apps.
+    #
+    # If you want to do anything from the list above on a general basis you can:
+    #
+    #   * write RSpec/Cucumber/etc. after hook
+    #   * monkeypatch this method
+    #   * use Ruby's `prepend` method
     #
     def reset!
       if @touched