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

Conflicts:
	actionmailer/lib/action_mailer/base.rb
	activesupport/lib/active_support/core_ext/kernel/requires.rb

README.rdoc

@@ -1,30 +1,35 @@
 == Welcome to Rails
 
 Rails is a web-application framework that includes everything needed to create
-database-backed web applications according to the Model-View-Control pattern.
-
-This pattern splits the view (also called the presentation) into "dumb"
-templates that are primarily responsible for inserting pre-built data in between
-HTML tags. The model contains the "smart" domain objects (such as Account,
-Product, Person, Post) that holds all the business logic and knows how to
-persist themselves to a database. The controller handles the incoming requests
-(such as Save New Account, Update Product, Show Post) by manipulating the model
-and directing data to the view.
-
-In Rails, the model is handled by what's called an object-relational mapping
-layer entitled Active Record. This layer allows you to present the data from
-database rows as objects and embellish these data objects with business logic
-methods. You can read more about Active Record in its
+database-backed web applications according to the Model-View-Controller pattern. 
+
+Understanding the MVC pattern is key to understanding Rails.  MVC divides your application
+into three layers, each with a specific responsibility.
+
+The View layer is composed of "templates" that are responsible for providing 
+appropriate representations of your application's resources.  Templates
+can come in a variety of formats, but most view templates are HTML with embedded Ruby 
+code (.erb files). 
+
+The Model layer represents your domain model (such as Account, Product, Person, Post) 
+and encapsulates the business logic that is specific to your application. In Rails, 
+database-backed model classes are derived from ActiveRecord::Base. ActiveRecord allows
+you to present the data from database rows as objects and embellish these data objects 
+with business logic methods. Although most Rails models are backed by a database, models 
+can also be ordinary Ruby classes, or Ruby classes that implement a set of interfaces as
+provided by the ActiveModel module. You can read more about Active Record in its
 {README}[link:files/activerecord/README_rdoc.html].
 
-The controller and view are handled by the Action Pack, which handles both
-layers by its two parts: Action View and Action Controller. These two layers
-are bundled in a single package due to their heavy interdependence. This is
-unlike the relationship between the Active Record and Action Pack that is much
-more separate. Each of these packages can be used independently outside of
-Rails. You can read more about Action Pack in its
-{README}[link:files/actionpack/README_rdoc.html].
+The Controller layer is responsible for handling incoming HTTP requests and providing a 
+suitable response.  Usually this means returning HTML, but Rails controllers can also 
+generate XML, JSON, PDFs, mobile-specific views, and more. Controllers manipulate models 
+and render view templates in order to generate the appropriate HTTP response.
 
+In Rails, the Controller and View layers are handled together by Action Pack.
+These two layers are bundled in a single package due to their heavy interdependence. 
+This is unlike the relationship between the Active Record and Action Pack which are
+independent. Each of these packages can be used independently outside of Rails. You 
+can read more about Action Pack in its {README}[link:files/actionpack/README_rdoc.html].
 
 == Getting Started
 
@@ -60,9 +65,10 @@ Rails. You can read more about Action Pack in its
 == Contributing
 
 We encourage you to contribute to Ruby on Rails! Please check out the {Contributing to Rails
-guide}[http://edgeguides.rubyonrails.org/contributing_to_rails.html] for guidelines about how
+guide}[http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html] for guidelines about how
 to proceed. {Join us}[http://contributors.rubyonrails.org]!
 
 == License
 
 Ruby on Rails is released under the MIT license.
+

actionmailer/README.rdoc

@@ -153,7 +153,7 @@ Action Mailer is released under the MIT license.
 
 API documentation is at
 
-* http://api.rubyonrails.com
+* http://api.rubyonrails.org
 
 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
 

actionmailer/lib/action_mailer/base.rb

@@ -212,15 +212,15 @@ module ActionMailer #:nodoc:
   #
   # = Observing and Intercepting Mails
   #
-  # Action Mailer provides hooks into the Mail observer and interceptor methods.  These allow you to
+  # Action Mailer provides hooks into the Mail observer and interceptor methods. These allow you to
   # register objects that are called during the mail delivery life cycle.
   #
   # An observer object must implement the <tt>:delivered_email(message)</tt> method which will be
   # called once for every email sent after the email has been sent.
   #
   # An interceptor object must implement the <tt>:delivering_email(message)</tt> method which will be
   # called before the email is sent, allowing you to make modifications to the email before it hits
-  # the delivery agents.  Your object should make any needed modifications directly to the passed
+  # the delivery agents. Your object should make any needed modifications directly to the passed
   # in Mail::Message instance.
   #
   # = Default Hash
@@ -311,11 +311,11 @@ module ActionMailer #:nodoc:
   #
   # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default),
   #   <tt>:sendmail</tt>, <tt>:test</tt>, and <tt>:file</tt>. Or you may provide a custom delivery method
-  #   object eg. MyOwnDeliveryMethodClass.new.  See the Mail gem documentation on the interface you need to
+  #   object eg. MyOwnDeliveryMethodClass.new. See the Mail gem documentation on the interface you need to
   #   implement for a custom delivery agent.
   #
   # * <tt>perform_deliveries</tt> - Determines whether emails are actually sent from Action Mailer when you
-  #   call <tt>.deliver</tt> on an mail message or on an Action Mailer method.  This is on by default but can
+  #   call <tt>.deliver</tt> on an mail message or on an Action Mailer method. This is on by default but can
   #   be turned off to aid in functional testing.
   #
   # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with
@@ -549,8 +549,8 @@ def attachments
     # method.
     #
     # When a <tt>:return_path</tt> is specified as header, that value will be used as the 'envelope from'
-    # address for the Mail message.  Setting this is useful when you want delivery notifications
-    # sent to a different address than the one in <tt>:from</tt>.  Mail will actually use the
+    # address for the Mail message. Setting this is useful when you want delivery notifications
+    # sent to a different address than the one in <tt>:from</tt>. Mail will actually use the
     # <tt>:return_path</tt> in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt>
     # field for the 'envelope from' value.
     #

actionpack/README.rdoc

@@ -334,7 +334,7 @@ Action Pack is released under the MIT license.
 
 API documentation is at
 
-* http://api.rubyonrails.com
+* http://api.rubyonrails.org
 
 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
 

actionpack/lib/abstract_controller/base.rb

@@ -10,7 +10,7 @@ class ActionNotFound < StandardError; end
   # <tt>AbstractController::Base</tt> is a low-level API. Nobody should be
   # using it directly, and subclasses (like ActionController::Base) are
   # expected to provide their own +render+ method, since rendering means
-  # different things depending on the context.  
+  # different things depending on the context.
   class Base
     attr_internal :response_body
     attr_internal :action_name

actionpack/lib/abstract_controller/helpers.rb

@@ -67,7 +67,7 @@ def #{meth}(*args, &blk)
       #   helper FooHelper # => includes FooHelper
       #
       # When the argument is a string or symbol, the method will provide the "_helper" suffix, require the file
-      # and include the module in the template class.  The second form illustrates how to include custom helpers
+      # and include the module in the template class. The second form illustrates how to include custom helpers
       # when working with namespaced controllers, or other cases where the file containing the helper definition is not
       # in one of Rails' standard load paths:
       #   helper :foo             # => requires 'foo_helper' and includes FooHelper

actionpack/lib/action_controller/caching/actions.rb

@@ -39,8 +39,8 @@ module Caching
     # <tt>:action => 'list', :format => :xml</tt>.
     #
     # You can set modify the default action cache path by passing a
-    # <tt>:cache_path</tt> option.  This will be passed directly to
-    # <tt>ActionCachePath.path_for</tt>.  This is handy for actions with
+    # <tt>:cache_path</tt> option. This will be passed directly to
+    # <tt>ActionCachePath.path_for</tt>. This is handy for actions with
     # multiple possible routes that should be cached differently. If a
     # block is given, it is called with the current controller instance.
     #

actionpack/lib/action_controller/metal/data_streaming.rb

@@ -37,7 +37,7 @@ module DataStreaming
       #
       # The default Content-Type and Content-Disposition headers are
       # set to download arbitrary binary files in as many browsers as
-      # possible.  IE versions 4, 5, 5.5, and 6 are all known to have
+      # possible. IE versions 4, 5, 5.5, and 6 are all known to have
       # a variety of quirks (especially when downloading over SSL).
       #
       # Simple download:
@@ -58,8 +58,8 @@ module DataStreaming
       #
       # Also be aware that the document may be cached by proxies and browsers.
       # The Pragma and Cache-Control headers declare how the file may be cached
-      # by intermediaries.  They default to require clients to validate with
-      # the server before releasing cached responses.  See
+      # by intermediaries. They default to require clients to validate with
+      # the server before releasing cached responses. See
       # http://www.mnot.net/cache_docs/ for an overview of web caching and
       # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
       # for the Cache-Control header spec.

actionpack/lib/action_controller/metal/force_ssl.rb

@@ -1,12 +1,12 @@
 module ActionController
-  # This module provides a method which will redirects browser to use HTTPS
+  # This module provides a method which will redirect browser to use HTTPS
   # protocol. This will ensure that user's sensitive information will be
   # transferred safely over the internet. You _should_ always force browser
   # to use HTTPS when you're transferring sensitive information such as
   # user authentication, account information, or credit card information.
   #
-  # Note that if you really concern about your application safety, you might
-  # consider using +config.force_ssl+ in your configuration config file instead.
+  # Note that if you are really concerned about your application security,
+  # you might consider using +config.force_ssl+ in your config file instead.
   # That will ensure all the data transferred via HTTPS protocol and prevent
   # user from getting session hijacked when accessing the site under unsecured
   # HTTP protocol.

actionpack/lib/action_controller/metal/http_authentication.rb

@@ -400,7 +400,7 @@ def request_http_token_authentication(realm = "Application")
       # the present token and options.
       #
       # controller      - ActionController::Base instance for the current request.
-      # login_procedure - Proc to call if a token is present.  The Proc should
+      # login_procedure - Proc to call if a token is present. The Proc should
       #                   take 2 arguments:
       #                     authenticate(controller) { |token, options| ... }
       #
@@ -413,7 +413,7 @@ def authenticate(controller, &login_procedure)
         end
       end
 
-      # Parses the token and options out of the token authorization header.  If
+      # Parses the token and options out of the token authorization header. If
       # the header looks like this:
       #   Authorization: Token token="abc", nonce="def"
       # Then the returned token is "abc", and the options is {:nonce => "def"}

actionpack/lib/action_controller/metal/request_forgery_protection.rb

@@ -63,15 +63,15 @@ module ClassMethods
       #
       # Valid Options:
       #
-      # * <tt>:only/:except</tt> - Passed to the <tt>before_filter</tt> call.  Set which actions are verified.
+      # * <tt>:only/:except</tt> - Passed to the <tt>before_filter</tt> call. Set which actions are verified.
       def protect_from_forgery(options = {})
         self.request_forgery_protection_token ||= :authenticity_token
         prepend_before_filter :verify_authenticity_token, options
       end
     end
 
     protected
-      # The actual before_filter that is used.  Modify this to change how you handle unverified requests.
+      # The actual before_filter that is used. Modify this to change how you handle unverified requests.
       def verify_authenticity_token
         unless verified_request?
           logger.debug "WARNING: Can't verify CSRF token authenticity" if logger
@@ -83,7 +83,7 @@ def handle_unverified_request
         reset_session
       end
 
-      # Returns true or false if a request is verified.  Checks:
+      # Returns true or false if a request is verified. Checks:
       #
       # * is it a GET request?  Gets should be safe and idempotent
       # * Does the form_authenticity_token match the given token value from the params?

actionpack/lib/action_controller/vendor/html-scanner/html/sanitizer.rb

@@ -103,7 +103,7 @@ class WhiteListSanitizer < Sanitizer
     # Specifies the default Set of allowed shorthand css properties for the #sanitize and #sanitize_css helpers.
     self.shorthand_css_properties = Set.new(%w(background border margin padding))
 
-    # Sanitizes a block of css code.  Used by #sanitize when it comes across a style attribute
+    # Sanitizes a block of css code. Used by #sanitize when it comes across a style attribute
     def sanitize_css(style)
       # disallow urls
       style = style.to_s.gsub(/url\s*\(\s*[^\s)]+?\s*\)\s*/, ' ')

actionpack/lib/action_dispatch/http/mime_type.rb

@@ -47,7 +47,7 @@ class Type
     cattr_reader :html_types
 
     # These are the content types which browsers can generate without using ajax, flash, etc
-    # i.e. following a link, getting an image or posting a form.  CSRF protection
+    # i.e. following a link, getting an image or posting a form. CSRF protection
     # only needs to protect against these types.
     @@browser_generated_types = Set.new [:html, :url_encoded_form, :multipart_form, :text]
     cattr_reader :browser_generated_types
@@ -246,7 +246,7 @@ def =~(mime_type)
       end
     end
 
-    # Returns true if Action Pack should check requests using this Mime Type for possible request forgery.  See
+    # Returns true if Action Pack should check requests using this Mime Type for possible request forgery. See
     # ActionController::RequestForgeryProtection.
     def verify_request?
       @@browser_generated_types.include?(to_sym)

actionpack/lib/action_dispatch/http/request.rb

@@ -166,10 +166,10 @@ def ip
        )\.
     }x
 
-    # Determines originating IP address.  REMOTE_ADDR is the standard
-    # but will fail if the user is behind a proxy.  HTTP_CLIENT_IP and/or
+    # Determines originating IP address. REMOTE_ADDR is the standard
+    # but will fail if the user is behind a proxy. HTTP_CLIENT_IP and/or
     # HTTP_X_FORWARDED_FOR are set by proxies so check for these if
-    # REMOTE_ADDR is a proxy.  HTTP_X_FORWARDED_FOR may be a comma-
+    # REMOTE_ADDR is a proxy. HTTP_X_FORWARDED_FOR may be a comma-
     # delimited list in the case of multiple chained proxies; the last
     # address which is not trusted is the originating IP.
     def remote_ip

actionpack/lib/action_dispatch/middleware/cookies.rb

@@ -59,7 +59,7 @@ def cookie_jar
   # The option symbols for setting cookies are:
   #
   # * <tt>:value</tt> - The cookie's value or list of values (as an array).
-  # * <tt>:path</tt> - The path for which this cookie applies.  Defaults to the root
+  # * <tt>:path</tt> - The path for which this cookie applies. Defaults to the root
   #   of the application.
   # * <tt>:domain</tt> - The domain for which this cookie applies so you can
   #   restrict to the domain level. If you use a schema like www.example.com

actionpack/lib/action_dispatch/routing/mapper.rb

@@ -335,7 +335,7 @@ def root(options = {})
         #
         # [:on]
         #   Shorthand for wrapping routes in a specific RESTful context. Valid
-        #   values are +:member+, +:collection+, and +:new+.  Only use within
+        #   values are +:member+, +:collection+, and +:new+. Only use within
         #   <tt>resource(s)</tt> block. For example:
         #
         #      resource :bar do
@@ -578,8 +578,8 @@ module Scoping
         #   end
         #
         # This generates helpers such as +account_projects_path+, just like +resources+ does.
-        # The difference here being that the routes generated are like /rails/projects/2,
-        # rather than /accounts/rails/projects/2.
+        # The difference here being that the routes generated are like /:account_id/projects,
+        # rather than /accounts/:account_id/projects.
         #
         # === Options
         #
@@ -1094,11 +1094,11 @@ def resource(*resources, &block)
         # [:shallow_path]
         #   Prefixes nested shallow routes with the specified path.
         #
-        #   scope :shallow_path => "sekret" do
-        #     resources :posts do
-        #       resources :comments, :shallow => true
+        #     scope :shallow_path => "sekret" do
+        #       resources :posts do
+        #         resources :comments, :shallow => true
+        #       end
         #     end
-        #   end
         #
         #   The +comments+ resource here will have the following routes generated for it:
         #

actionpack/lib/action_dispatch/routing/url_for.rb

@@ -108,7 +108,7 @@ def url_options
       end
 
       # Generate a url based on the options provided, default_url_options and the
-      # routes defined in routes.rb.  The following options are supported:
+      # routes defined in routes.rb. The following options are supported:
       #
       # * <tt>:only_path</tt> - If true, the relative url is returned. Defaults to +false+.
       # * <tt>:protocol</tt> - The protocol to connect to. Defaults to 'http'.