Merge branch 'master' of git@github.com:lifo/docrails

9 files changed, 80 insertions, 45 deletions

diff --git a/actionpack/README b/actionpack/README
index 2746c3cc43..6090089bb9 100644
--- a/actionpack/README
+++ b/actionpack/README
@@ -31,7 +31,7 @@ http://www.rubyonrails.org.
 A short rundown of the major features:
 
 * Actions grouped in controller as methods instead of separate command objects
-  and can therefore share helper methods.
+  and can therefore share helper methods
 
     BlogController < ActionController::Base
       def show
@@ -168,7 +168,7 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActionController/Base.html]
 
 
-* Javascript and Ajax integration.
+* Javascript and Ajax integration
 
     link_to_function "Greeting", "alert('Hello world!')"
     link_to_remote "Delete this post", :update => "posts", 
@@ -177,7 +177,7 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActionView/Helpers/JavaScriptHelper.html]
 
 
-* Pagination for navigating lists of results.
+* Pagination for navigating lists of results
 
     # controller
     def list
@@ -192,15 +192,9 @@ A short rundown of the major features:
   {Learn more}[link:classes/ActionController/Pagination.html]
 
 
-* Easy testing of both controller and template result through TestRequest/Response
-
-    class LoginControllerTest < Test::Unit::TestCase
-      def setup
-        @controller = LoginController.new
-        @request    = ActionController::TestRequest.new
-        @response   = ActionController::TestResponse.new
-      end
+* Easy testing of both controller and rendered template through ActionController::TestCase
 
+    class LoginControllerTest < ActionController::TestCase
       def test_failing_authenticate
         process :authenticate, :user_name => "nop", :password => ""
         assert flash.has_key?(:alert)
@@ -208,7 +202,7 @@ A short rundown of the major features:
       end
     end
 
-  {Learn more}[link:classes/ActionController/TestRequest.html]
+  {Learn more}[link:classes/ActionController/TestCase.html]
 
 
 * Automated benchmarking and integrated logging
diff --git a/actionpack/lib/action_controller/caching/fragments.rb b/actionpack/lib/action_controller/caching/fragments.rb
index e4f5de44ab..578e031a17 100644
--- a/actionpack/lib/action_controller/caching/fragments.rb
+++ b/actionpack/lib/action_controller/caching/fragments.rb
@@ -2,7 +2,7 @@ module ActionController #:nodoc:
   module Caching
     # Fragment caching is used for caching various blocks within templates without caching the entire action as a whole. This is useful when
     # certain elements of an action change frequently or depend on complicated state while other parts rarely change or can be shared amongst multiple
-    # parties. The caching is doing using the cache helper available in the Action View. A template with caching might look something like:
+    # parties. The caching is done using the cache helper available in the Action View. A template with caching might look something like:
     #
     #   <b>Hello <%= @name %></b>
     #   <% cache do %>
diff --git a/actionpack/lib/action_controller/test_case.rb b/actionpack/lib/action_controller/test_case.rb
index 77c6f26eac..f26e65ba34 100644
--- a/actionpack/lib/action_controller/test_case.rb
+++ b/actionpack/lib/action_controller/test_case.rb
@@ -15,6 +15,27 @@ module ActionController
     end
   end
 
+  # Superclass for Action Controller functional tests. Infers the controller under test from the test class name,
+  # and creates @controller, @request, @response instance variables.
+  #
+  #   class WidgetsControllerTest < ActionController::TestCase
+  #     def test_index
+  #       get :index
+  #     end
+  #   end
+  #
+  # * @controller - WidgetController.new
+  # * @request    - ActionController::TestRequest.new
+  # * @response   - ActionController::TestResponse.new
+  #
+  # (Earlier versions of Rails required each functional test to subclass Test::Unit::TestCase and define 
+  # @controller, @request, @response in +setup+.)
+  #
+  # If the controller cannot be inferred from the test class name, you can explicity set it with +tests+.
+  #
+  #   class SpecialEdgeCaseWidgetsControllerTest < ActionController::TestCase
+  #     tests WidgetController
+  #   end
   class TestCase < ActiveSupport::TestCase
     # When the request.remote_addr remains the default for testing, which is 0.0.0.0, the exception is simply raised inline
     # (bystepping the regular exception handling from rescue_action). If the request.remote_addr is anything else, the regular
@@ -41,6 +62,8 @@ module ActionController
     @@controller_class = nil
 
     class << self
+      # Sets the controller class name. Useful if the name can't be inferred from test class. 
+      # Expects +controller_class+ as a constant. Example: <tt>tests WidgetController</tt>.
       def tests(controller_class)
         self.controller_class = controller_class
       end
diff --git a/actionpack/lib/action_view/helpers/debug_helper.rb b/actionpack/lib/action_view/helpers/debug_helper.rb
index 20de7e465f..ea70a697de 100644
--- a/actionpack/lib/action_view/helpers/debug_helper.rb
+++ b/actionpack/lib/action_view/helpers/debug_helper.rb
@@ -2,21 +2,28 @@ module ActionView
   module Helpers
     # Provides a set of methods for making it easier to debug Rails objects.
     module DebugHelper
-      # Returns a <pre>-tag that has +object+ dumped by YAML. This creates a very
-      # readable way to inspect an object.
+      # Returns a YAML representation of +object+ wrapped with <pre> and </pre>.
+      # If the object cannot be converted to YAML using +to_yaml+, +inspect+ will be called instead.
+      # Useful for inspecting an object at the time of rendering.
       #
       # ==== Example
-      #  my_hash = {'first' => 1, 'second' => 'two', 'third' => [1,2,3]}
-      #  debug(my_hash)
       #
-      #  => <pre class='debug_dump'>--- 
-      #  first: 1
-      #  second: two
-      #  third: 
-      #  - 1
-      #  - 2
-      #  - 3
-      #  </pre>
+      #   @user = User.new({ :username => 'testing', :password => 'xyz', :age => 42}) %>
+      #   debug(@user)
+      #   # =>
+      #   <pre class='debug_dump'>--- !ruby/object:User 
+      #   attributes: 
+      #   &nbsp; updated_at: 
+      #   &nbsp; username: testing
+      #   
+      #   &nbsp; age: 42
+      #   &nbsp; password: xyz
+      #   &nbsp; created_at: 
+      #   attributes_cache: {}
+      #   
+      #   new_record: true
+      #   </pre>
+
       def debug(object)
         begin
           Marshal::dump(object)
@@ -28,4 +35,4 @@ module ActionView
       end
     end
   end
-end
\ No newline at end of file
+end
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index e0a097e367..c0cba24be4 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -271,9 +271,11 @@ module ActionView
         end
       end
 
-      # Returns a string of option tags for pretty much any country in the world. Supply a country name as +selected+ to
-      # have it marked as the selected option tag. You can also supply an array of countries as +priority_countries+, so
-      # that they will be listed above the rest of the (long) list.
+      # Returns a string of option tags for most countries in the
+      # world (as defined in COUNTRIES). Supply a country name as
+      # +selected+ to have it marked as the selected option tag. You
+      # can also supply an array of countries as +priority_countries+,
+      # so that they will be listed above the rest of the (long) list.
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
       def country_options_for_select(selected = nil, priority_countries = nil)
diff --git a/actionpack/lib/action_view/helpers/javascript_helper.rb b/actionpack/lib/action_view/helpers/javascript_helper.rb
index 1ea3cbd74e..ed931e064f 100644
--- a/actionpack/lib/action_view/helpers/javascript_helper.rb
+++ b/actionpack/lib/action_view/helpers/javascript_helper.rb
@@ -43,14 +43,23 @@ module ActionView
       end
 
       include PrototypeHelper
-      
-      # Returns a link that will trigger a JavaScript +function+ using the 
+
+      # Returns a link of the given +name+ that will trigger a JavaScript +function+ using the 
       # onclick handler and return false after the fact.
       #
+      # The first argument +name+ is used as the link text.
+      #
+      # The next arguments are optional and may include the javascript function definition and a hash of html_options.
+      #
       # The +function+ argument can be omitted in favor of an +update_page+
       # block, which evaluates to a string when the template is rendered
       # (instead of making an Ajax request first).      
       #
+      # The +html_options+ will accept a hash of html attributes for the link tag. Some examples are :class => "nav_button", :id => "articles_nav_button"
+      #
+      # Note: if you choose to specify the javascript function in a block, but would like to pass html_options, set the +function+ parameter to nil
+      #
+      #
       # Examples:
       #   link_to_function "Greeting", "alert('Hello world!')"
       #     Produces:
@@ -94,13 +103,21 @@ module ActionView
         )
       end
       
-      # Returns a button that'll trigger a JavaScript +function+ using the 
+      # Returns a button with the given +name+ text that'll trigger a JavaScript +function+ using the 
       # onclick handler.
       #
+      # The first argument +name+ is used as the button's value or display text.
+      #
+      # The next arguments are optional and may include the javascript function definition and a hash of html_options.
+      #
       # The +function+ argument can be omitted in favor of an +update_page+
       # block, which evaluates to a string when the template is rendered
       # (instead of making an Ajax request first).      
       #
+      # The +html_options+ will accept a hash of html attributes for the link tag. Some examples are :class => "nav_button", :id => "articles_nav_button"
+      #
+      # Note: if you choose to specify the javascript function in a block, but would like to pass html_options, set the +function+ parameter to nil
+      #
       # Examples:
       #   button_to_function "Greeting", "alert('Hello world!')"
       #   button_to_function "Delete", "if (confirm('Really?')) do_delete()"
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 4b12adf225..7bb189420b 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -173,7 +173,7 @@ module ActionView
       #   link_to "Nonsense search", searches_path(:foo => "bar", :baz => "quux")
       #   # => <a href="/searches?foo=bar&amp;baz=quux">Nonsense search</a>
       #
-      # The three options specfic to +link_to+ (<tt>:confirm</tt>, <tt>:popup</tt>, and <tt>:method</tt>) are used as follows:
+      # The three options specific to +link_to+ (<tt>:confirm</tt>, <tt>:popup</tt>, and <tt>:method</tt>) are used as follows:
       #
       #   link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?"
       #   # => <a href="http://www.rubyonrails.org/" onclick="return confirm('Are you sure?');">Visit Other Site</a>
diff --git a/actionpack/lib/action_view/test_case.rb b/actionpack/lib/action_view/test_case.rb
index b2e6589d81..16fedd9732 100644
--- a/actionpack/lib/action_view/test_case.rb
+++ b/actionpack/lib/action_view/test_case.rb
@@ -1,14 +1,6 @@
 require 'active_support/test_case'
 
 module ActionView
-  class NonInferrableHelperError < ActionViewError
-    def initialize(name)
-      super "Unable to determine the helper to test from #{name}. " +
-        "You'll need to specify it using tests YourHelper in your " +
-        "test case definition"
-    end
-  end
-
   class TestCase < ActiveSupport::TestCase
     class_inheritable_accessor :helper_class
     @@helper_class = nil
@@ -29,7 +21,7 @@ module ActionView
       def determine_default_helper_class(name)
         name.sub(/Test$/, '').constantize
       rescue NameError
-        raise NonInferrableHelperError.new(name)
+        nil
       end
     end
 
@@ -42,7 +34,9 @@ module ActionView
     setup :setup_with_helper_class
 
     def setup_with_helper_class
-      self.class.send(:include, helper_class)
+      if helper_class && !self.class.ancestors.include?(helper_class)
+        self.class.send(:include, helper_class)
+      end
     end
 
     class TestController < ActionController::Base
diff --git a/actionpack/test/template/prototype_helper_test.rb b/actionpack/test/template/prototype_helper_test.rb
index 5e00eadb8d..53a250f9d5 100644
--- a/actionpack/test/template/prototype_helper_test.rb
+++ b/actionpack/test/template/prototype_helper_test.rb
@@ -25,8 +25,6 @@ class Author::Nested < Author; end
 
 
 class PrototypeHelperBaseTest < ActionView::TestCase
-  tests ActionView::Helpers::PrototypeHelper
-
   attr_accessor :template_format
 
   def setup