Merge branch 'master' of github.com:rails/docrails

activesupport/lib/active_support/cache/file_store.rb

@@ -22,11 +22,15 @@ def initialize(cache_path, options = nil)
         extend Strategy::LocalCache
       end
 
+      # Deletes all items from the cache. In this case it deletes all the entries in the specified 
+      # file store directory except for .gitkeep. Be careful which directory is specified in your 
+      # config file when using +FileStore+ because everything in that directory will be deleted.
       def clear(options = nil)
         root_dirs = Dir.entries(cache_path).reject {|f| (EXCLUDED_DIRS + [".gitkeep"]).include?(f)}
         FileUtils.rm_r(root_dirs.collect{|f| File.join(cache_path, f)})
       end
 
+      # Premptively iterates through all stored keys and removes the ones which have expired.
       def cleanup(options = nil)
         options = merged_options(options)
         each_key(options) do |key|
@@ -35,6 +39,8 @@ def cleanup(options = nil)
         end
       end
 
+      # Increments an already existing integer value that is stored in the cache.
+      # If the key is not found nothing is done.
       def increment(name, amount = 1, options = nil)
         file_name = key_file_path(namespaced_key(name, options))
         lock_file(file_name) do
@@ -49,6 +55,8 @@ def increment(name, amount = 1, options = nil)
         end
       end
 
+      # Decrements an already existing integer value that is stored in the cache.
+      # If the key is not found nothing is done.
       def decrement(name, amount = 1, options = nil)
         file_name = key_file_path(namespaced_key(name, options))
         lock_file(file_name) do

activesupport/lib/active_support/cache/memory_store.rb

@@ -36,6 +36,7 @@ def clear(options = nil)
         end
       end
 
+      # Premptively iterates through all stored keys and removes the ones which have expired.
       def cleanup(options = nil)
         options = merged_options(options)
         instrument(:cleanup, :size => @data.size) do

activesupport/lib/active_support/core_ext/array/conversions.rb

@@ -82,23 +82,8 @@ def to_sentence(options = {})
     end
   end
 
-  # Converts a collection of elements into a formatted string by calling
-  # <tt>to_s</tt> on all elements and joining them. Having this model:
-  #
-  #   class Blog < ActiveRecord::Base
-  #     def to_s
-  #       title
-  #     end
-  #   end
-  #
-  #   Blog.all.map(&:title) #=> ["First Post", "Second Post", "Third post"]
-  #
-  # <tt>to_formatted_s</tt> shows us:
-  #
-  #   Blog.all.to_formatted_s # => "First PostSecond PostThird Post"
-  #
-  # Adding in the <tt>:db</tt> argument as the format yields a comma separated
-  # id list:
+  # Extends <tt>Array#to_s</tt> to convert a collection of elements into a
+  # comma separated id list if <tt>:db</tt> argument is given as the format.
   #
   #   Blog.all.to_formatted_s(:db) # => "1,2,3"
   def to_formatted_s(format = :default)

activesupport/lib/active_support/core_ext/module/delegation.rb

@@ -6,6 +6,11 @@ class DelegationError < NoMethodError; end
   # Provides a +delegate+ class method to easily expose contained objects'
   # public methods as your own.
   #
+  # ==== Options
+  # * <tt>:to</tt> - Specifies the target object
+  # * <tt>:prefix</tt> - Prefixes the new method with the target name or a custom prefix
+  # * <tt>:allow_nil</tt> - if set to true, prevents a +NoMethodError+ to be raised
+  #
   # The macro receives one or more method names (specified as symbols or
   # strings) and the name of the target object via the <tt>:to</tt> option
   # (also a symbol or string).

guides/source/command_line.md

@@ -222,7 +222,7 @@ We will set up a simple resource called "HighScore" that will keep track of our
 ```bash
 $ rails generate scaffold HighScore game:string score:integer
     invoke  active_record
-    create    db/migrate/20120528060026_create_high_scores.rb
+    create    db/migrate/20130717151933_create_high_scores.rb
     create    app/models/high_score.rb
     invoke    test_unit
     create      test/models/high_score_test.rb
@@ -244,18 +244,21 @@ $ rails generate scaffold HighScore game:string score:integer
     create      app/helpers/high_scores_helper.rb
     invoke      test_unit
     create        test/helpers/high_scores_helper_test.rb
+    invoke    jbuilder
+    create      app/views/high_scores/index.json.jbuilder
+    create      app/views/high_scores/show.json.jbuilder
     invoke  assets
     invoke    coffee
     create      app/assets/javascripts/high_scores.js.coffee
     invoke    scss
     create      app/assets/stylesheets/high_scores.css.scss
     invoke  scss
-    create    app/assets/stylesheets/scaffolds.css.scss
+   identical    app/assets/stylesheets/scaffolds.css.scss
 ```
 
 The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the `high_scores` table and fields), takes care of the route for the **resource**, and new tests for everything.
 
-The migration requires that we **migrate**, that is, run some Ruby code (living in that `20120528060026_create_high_scores.rb`) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the `rake db:migrate` command. We'll talk more about Rake in-depth in a little while.
+The migration requires that we **migrate**, that is, run some Ruby code (living in that `20130717151933_create_high_scores.rb`) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the `rake db:migrate` command. We'll talk more about Rake in-depth in a little while.
 
 ```bash
 $ rake db:migrate
@@ -384,7 +387,7 @@ Active Record version     4.0.0
 Action Pack version       4.0.0
 Action Mailer version     4.0.0
 Active Support version    4.0.0
-Middleware                ActionDispatch::Static, Rack::Lock, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::DebugExceptions, ActionDispatch::RemoteIp, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActiveRecord::ConnectionAdapters::ConnectionManagement, ActiveRecord::QueryCache, ActionDispatch::Cookies, ActionDispatch::Session::EncryptedCookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::Head, Rack::ConditionalGet, Rack::ETag
+Middleware                Rack::Sendfile, ActionDispatch::Static, Rack::Lock, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::DebugExceptions, ActionDispatch::RemoteIp, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActiveRecord::ConnectionAdapters::ConnectionManagement, ActiveRecord::QueryCache, ActionDispatch::Cookies, ActionDispatch::Session::EncryptedCookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::Head, Rack::ConditionalGet, Rack::ETag
 Application root          /home/foobar/commandsapp
 Environment               development
 Database adapter          sqlite3

guides/source/debugging_rails_applications.md

@@ -301,7 +301,7 @@ This command shows you where you are in the code by printing 10 lines centered a
    7
    8      respond_to do |format|
    9        format.html # index.html.erb
-   10        format.json { render :json => @posts }
+   10        format.json { render json: @posts }
 ```
 
 If you repeat the `list` command, this time using just `l`, the next ten lines of the file will be printed out.
@@ -337,7 +337,7 @@ On the other hand, to see the previous ten lines you should type `list-` (or `l-
    7
    8      respond_to do |format|
    9        format.html # index.html.erb
-   10        format.json { render :json => @posts }
+   10        format.json { render json: @posts }
 ```
 
 This way you can move inside the file, being able to see the code above and over the line you added the `debugger`.

guides/source/engines.md

@@ -393,10 +393,15 @@ The form will be making a `POST` request to `/posts/:post_id/comments`, which wi
 ```ruby
 def create
   @post = Post.find(params[:post_id])
-  @comment = @post.comments.create(params[:comment])
+  @comment = @post.comments.create(comment_params)
   flash[:notice] = "Comment has been created!"
   redirect_to posts_path
 end
+
+private
+def comment_params
+  params.require(:comment).permit(:text)
+end
 ```
 
 This is the final part required to get the new comment form working. Displaying the comments however, is not quite right yet. If you were to create a comment right now you would see this error:

guides/source/getting_started.md

@@ -972,7 +972,7 @@ appear next to the "Show" link:
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', post_path(post) %></td>
+    <td><%= link_to 'Show', post %></td>
     <td><%= link_to 'Edit', edit_post_path(post) %></td>
   </tr>
 <% end %>

guides/source/plugins.md

@@ -136,7 +136,7 @@ To begin, set up your files so that you have:
 
 require 'test_helper'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class ActsAsYaffleTest < ActiveSupport::TestCase
 end
 ```
 
@@ -173,7 +173,7 @@ To start out, write a failing test that shows the behavior you'd like:
 
 require 'test_helper'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class ActsAsYaffleTest < ActiveSupport::TestCase
 
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
     assert_equal "last_squawk", Hickwall.yaffle_text_field
@@ -321,7 +321,7 @@ To start out, write a failing test that shows the behavior you'd like:
 # yaffle/test/acts_as_yaffle_test.rb
 require 'test_helper'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class ActsAsYaffleTest < ActiveSupport::TestCase
 
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
     assert_equal "last_squawk", Hickwall.yaffle_text_field

guides/source/rails_on_rack.md

@@ -119,6 +119,7 @@ $ rake middleware
 For a freshly generated Rails application, this might produce something like:
 
 ```ruby
+use Rack::Sendfile
 use ActionDispatch::Static
 use Rack::Lock
 use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x000000029a0838>

railties/lib/rails/console/helpers.rb

 module Rails
   module ConsoleMethods
+    # Gets the helper methods available to the controller.
+    #
+    # This method assumes an +ApplicationController+ exists, and it extends +ActionController::Base+
     def helper
       @helper ||= ApplicationController.helpers
     end
 
+    # Gets a new instance of a controller object.
+    #
+    # This method assumes an +ApplicationController+ exists, and it extends +ActionController::Base+
     def controller
       @controller ||= ApplicationController.new
     end