Massive documentation update for all helpers (closes #8223, #8177, #8175, #8108, #7977, #7972, #7971, #7969) [jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7106 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 12 insertions, 5 deletions

diff --git a/actionpack/lib/action_view/helpers/benchmark_helper.rb b/actionpack/lib/action_view/helpers/benchmark_helper.rb
index 1d53be51db..fefa28f4d7 100644
--- a/actionpack/lib/action_view/helpers/benchmark_helper.rb
+++ b/actionpack/lib/action_view/helpers/benchmark_helper.rb
@@ -2,17 +2,24 @@ require 'benchmark'
 
 module ActionView
   module Helpers
+    # This helper offers a method to measure the execution time of a block 
+    # in a template.
     module BenchmarkHelper
-      # Measures the execution time of a block in a template and reports the result to the log. Example:
+      # Allows you to measure the execution time of a block 
+      # in a template and records the result to the log. Wrap this block around
+      # expensive operations or possible bottlenecks to get a time reading
+      # for the operation.  For example, let's say you thought your file 
+      # processing method was taking too long; you could wrap it in a benchmark block.
       #
-      #  <% benchmark "Notes section" do %>
-      #    <%= expensive_notes_operation %>
+      #  <% benchmark "Process data files" do %>
+      #    <%= expensive_files_operation %>
       #  <% end %>
       #
-      # Will add something like "Notes section (0.34523)" to the log.
+      # That would add something like "Process data files (0.34523)" to the log,
+      # which you can then use to compare timings when optimizing your code.
       #
       # You may give an optional logger level as the second argument
-      # (:debug, :info, :warn, :error).  The default is :info.
+      # (:debug, :info, :warn, :error); the default value is :info.
       def benchmark(message = "Benchmarking", level = :info)
         if @logger
           real = Benchmark.realtime { yield }