Permalink
Browse files

Merge remote branch 'docrails/master'

  • Loading branch information...
2 parents 3b62667 + 279c395 commit dda515fc2654199d3aaeb960a0ba1b7a395dfa48 @fxn fxn committed Aug 27, 2010
Showing with 129 additions and 138 deletions.
  1. +2 −2 actionpack/lib/action_controller/caching.rb
  2. +7 −7 actionpack/lib/action_controller/caching/actions.rb
  3. +3 −3 actionpack/lib/action_controller/caching/fragments.rb
  4. +13 −15 actionpack/lib/action_controller/metal.rb
  5. +6 −6 actionpack/lib/action_controller/metal/conditional_get.rb
  6. +11 −13 actionpack/lib/action_controller/metal/helpers.rb
  7. +2 −3 actionpack/lib/action_controller/metal/hide_actions.rb
  8. +18 −14 actionpack/lib/action_controller/metal/http_authentication.rb
  9. +18 −36 actionpack/lib/action_controller/metal/request_forgery_protection.rb
  10. +5 −5 actionpack/lib/action_controller/metal/responder.rb
  11. +4 −4 actionpack/lib/action_controller/test_case.rb
  12. +1 −1 actionpack/lib/action_dispatch/http/mime_negotiation.rb
  13. +2 −2 actionpack/lib/action_dispatch/http/url.rb
  14. +11 −2 actionpack/lib/action_dispatch/middleware/cookies.rb
  15. +7 −2 actionpack/lib/action_dispatch/middleware/flash.rb
  16. +1 −1 actionpack/lib/action_dispatch/testing/assertions/dom.rb
  17. +5 −5 actionpack/lib/action_dispatch/testing/assertions/response.rb
  18. +2 −2 actionpack/lib/action_dispatch/testing/assertions/routing.rb
  19. +1 −1 actionpack/lib/action_view/helpers/tag_helper.rb
  20. +1 −1 activesupport/lib/active_support/deprecation/proxy_wrappers.rb
  21. +1 −1 railties/guides/source/action_view_overview.textile
  22. +1 −1 railties/guides/source/active_record_validations_callbacks.textile
  23. +6 −10 railties/guides/source/getting_started.textile
  24. +1 −1 railties/guides/source/performance_testing.textile
@@ -3,7 +3,7 @@
require 'set'
module ActionController #:nodoc:
- # Caching is a cheap way of speeding up slow applications by keeping the result of
+ # \Caching is a cheap way of speeding up slow applications by keeping the result of
# calculations, renderings, and database calls around for subsequent requests.
# Action Controller affords you three approaches in varying levels of granularity:
# Page, Action, Fragment.
@@ -14,7 +14,7 @@ module ActionController #:nodoc:
# Note: To turn off all caching and sweeping, set
# config.action_controller.perform_caching = false.
#
- # == Caching stores
+ # == \Caching stores
#
# All the caching stores from ActiveSupport::Cache are available to be used as backends
# for Action Controller caching. This setting only affects action and fragment caching
@@ -23,15 +23,15 @@ module Caching
# Action caching internally uses the fragment caching and an around
# filter to do the job. The fragment cache is named according to both
# the current host and the path. So a page that is accessed at
- # http://david.somewhere.com/lists/show/1 will result in a fragment named
- # "david.somewhere.com/lists/show/1". This allows the cacher to
- # differentiate between "david.somewhere.com/lists/" and
- # "jamis.somewhere.com/lists/" -- which is a helpful way of assisting
+ # <tt>http://david.example.com/lists/show/1</tt> will result in a fragment named
+ # <tt>david.example.com/lists/show/1</tt>. This allows the cacher to
+ # differentiate between <tt>david.example.com/lists/</tt> and
+ # <tt>jamis.example.com/lists/</tt> -- which is a helpful way of assisting
# the subdomain-as-account-key pattern.
#
# Different representations of the same resource, e.g.
- # <tt>http://david.somewhere.com/lists</tt> and
- # <tt>http://david.somewhere.com/lists.xml</tt>
+ # <tt>http://david.example.com/lists</tt> and
+ # <tt>http://david.example.com/lists.xml</tt>
# are treated like separate requests and so are cached separately.
# Keep in mind when expiring an action cache that
# <tt>:action => 'lists'</tt> is not the same as
@@ -144,7 +144,7 @@ class ActionCachePath
attr_reader :path, :extension
# If +infer_extension+ is true, the cache path extension is looked up from the request's
- # path & format. This is desirable when reading and writing the cache, but not when
+ # path and format. This is desirable when reading and writing the cache, but not when
# expiring the cache - expire_action should expire the same files regardless of the
# request format.
def initialize(controller, options = {}, infer_extension = true)
@@ -18,7 +18,7 @@ module Caching
#
# <% cache(:action => "list", :action_suffix => "all_topics") do %>
#
- # That would result in a name such as "/topics/list/all_topics", avoiding conflicts with the action cache and with any fragments that use a
+ # That would result in a name such as <tt>/topics/list/all_topics</tt>, avoiding conflicts with the action cache and with any fragments that use a
# different suffix. Note that the URL doesn't have to really exist or be callable - the url_for system is just used to generate unique
# cache names that we can refer to when we need to expire the cache.
#
@@ -28,7 +28,7 @@ module Caching
module Fragments
# Given a key (as described in <tt>expire_fragment</tt>), returns a key suitable for use in reading,
# writing, or expiring a cached fragment. If the key is a hash, the generated key is the return
- # value of url_for on that hash (without the protocol). All keys are prefixed with "views/" and uses
+ # value of url_for on that hash (without the protocol). All keys are prefixed with <tt>views/</tt> and uses
# ActiveSupport::Cache.expand_cache_key for the expansion.
def fragment_cache_key(key)
ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views)
@@ -71,7 +71,7 @@ def fragment_exist?(key, options = nil)
#
# +key+ can take one of three forms:
# * String - This would normally take the form of a path, like
- # <tt>"pages/45/notes"</tt>.
+ # <tt>pages/45/notes</tt>.
# * Hash - Treated as an implicit call to +url_for+, like
# <tt>{:controller => "pages", :action => "notes", :id => 45}</tt>
# * Regexp - Will remove any fragment that matches, so
@@ -43,28 +43,28 @@ def build(action, app=nil, &block)
end
end
- # ActionController::Metal provides a way to get a valid Rack application from a controller.
+ # Provides a way to get a valid Rack application from a controller.
#
# In AbstractController, dispatching is triggered directly by calling #process on a new controller.
- # ActionController::Metal provides an #action method that returns a valid Rack application for a
- # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the Rails router,
- # can dispatch directly to the action returned by FooController.action(:index).
+ # <tt>ActionController::Metal</tt> provides an <tt>action</tt> method that returns a valid Rack application for a
+ # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the \Rails router,
+ # can dispatch directly to actions returned by controllers in your application.
class Metal < AbstractController::Base
abstract!
attr_internal :env
# Returns the last part of the controller's name, underscored, without the ending
- # "Controller". For instance, MyApp::MyPostsController would return "my_posts" for
- # controller_name
+ # <tt>Controller</tt>. For instance, PostsController returns <tt>posts</tt>.
+ # Namespaces are left out, so Admin::PostsController returns <tt>posts</tt> as well.
#
# ==== Returns
- # String
+ # * <tt>string</tt>
def self.controller_name
@controller_name ||= self.name.demodulize.sub(/Controller$/, '').underscore
end
- # Delegates to the class' #controller_name
+ # Delegates to the class' <tt>controller_name</tt>
def controller_name
self.class.controller_name
end
@@ -95,7 +95,7 @@ def params=(val)
# Basic implementations for content_type=, location=, and headers are
# provided to reduce the dependency on the RackDelegation module
# in Renderer and Redirector.
-
+
def content_type=(type)
headers["Content-Type"] = type.to_s
end
@@ -125,17 +125,15 @@ def response_body=(val)
super body
end
- # :api: private
- def dispatch(name, request)
+ def dispatch(name, request) #:nodoc:
@_request = request
@_env = request.env
@_env['action_controller.instance'] = self
process(name)
to_a
end
- # :api: private
- def to_a
+ def to_a #:nodoc:
response ? response.to_a : [status, headers, response_body]
end
@@ -164,10 +162,10 @@ def self.call(env)
# for the same action.
#
# ==== Parameters
- # action<#to_s>:: An action name
+ # * <tt>action</tt> - An action name
#
# ==== Returns
- # Proc:: A rack application
+ # * <tt>proc</tt> - A rack application
def self.action(name, klass = ActionDispatch::Request)
middleware_stack.build(name.to_s) do |env|
new.dispatch(name, klass.new(env))
@@ -6,7 +6,7 @@ module ConditionalGet
include Head
# Sets the etag, last_modified, or both on the response and renders a
- # "304 Not Modified" response if the request is already fresh.
+ # <tt>304 Not Modified</tt> response if the request is already fresh.
#
# Parameters:
# * <tt>:etag</tt>
@@ -21,7 +21,7 @@ module ConditionalGet
# end
#
# This will render the show template if the request isn't sending a matching etag or
- # If-Modified-Since header and just a "304 Not Modified" response if there's a match.
+ # If-Modified-Since header and just a <tt>304 Not Modified</tt> response if there's a match.
#
def fresh_when(options)
options.assert_valid_keys(:etag, :last_modified, :public)
@@ -36,7 +36,7 @@ def fresh_when(options)
# Sets the etag and/or last_modified on the response and checks it against
# the client request. If the request doesn't match the options provided, the
# request is considered stale and should be generated from scratch. Otherwise,
- # it's fresh and we don't need to generate anything and a reply of "304 Not Modified" is sent.
+ # it's fresh and we don't need to generate anything and a reply of <tt>304 Not Modified</tt> is sent.
#
# Parameters:
# * <tt>:etag</tt>
@@ -60,8 +60,8 @@ def stale?(options)
!request.fresh?(response)
end
- # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a "private" instruction, so that
- # intermediate caches shouldn't cache the response.
+ # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a <tt>private</tt> instruction, so that
+ # intermediate caches must not cache the response.
#
# Examples:
# expires_in 20.minutes
@@ -77,7 +77,7 @@ def expires_in(seconds, options = {}) #:doc:
response.cache_control[:extras] = options.map {|k,v| "#{k}=#{v}"}
end
- # Sets a HTTP 1.1 Cache-Control header of "no-cache" so no caching should occur by the browser or
+ # Sets a HTTP 1.1 Cache-Control header of <tt>no-cache</tt> so no caching should occur by the browser or
# intermediate caches (like caching proxy servers).
def expires_now #:doc:
response.cache_control.replace(:no_cache => true)
@@ -2,21 +2,21 @@
require 'active_support/core_ext/class/attribute'
module ActionController
- # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+,
- # +numbers+ and model objects, to name a few. These helpers are available to all templates
+ # The \Rails framework provides a large number of helpers for working with assets, dates, forms,
+ # numbers and model objects, to name a few. These helpers are available to all templates
# by default.
#
- # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to
+ # In addition to using the standard template helpers provided, creating custom helpers to
# extract complicated logic or reusable functionality is strongly encouraged. By default, the controller will
# include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically
# include <tt>MyHelper</tt>.
#
- # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any
+ # Additional helpers can be specified using the +helper+ class method in ActionController::Base or any
# controller which inherits from it.
#
# ==== Examples
- # The +to_s+ method from the Time class can be wrapped in a helper method to display a custom message if
- # the Time object is blank:
+ # The +to_s+ method from the \Time class can be wrapped in a helper method to display a custom message if
+ # a \Time object is blank:
#
# module FormattedTimeHelper
# def format_time(time, format=:long, blank_message="&nbsp;")
@@ -71,12 +71,11 @@ def helpers_dir=(value)
# Declares helper accessors for controller attributes. For example, the
# following adds new +name+ and <tt>name=</tt> instance methods to a
# controller and makes them available to the view:
- # helper_attr :name
# attr_accessor :name
+ # helper_attr :name
#
# ==== Parameters
- # *attrs<Array[String, Symbol]>:: Names of attributes to be converted
- # into helpers.
+ # * <tt>attrs</tt> - Names of attributes to be converted into helpers.
def helper_attr(*attrs)
attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
end
@@ -91,17 +90,16 @@ def helpers
# all helpers in helpers_dir.
#
# ==== Parameters
- # args<Array[String, Symbol, Module, all]>:: A list of helpers
+ # * <tt>args</tt> - A list of helpers
#
# ==== Returns
- # Array[Module]:: A normalized list of modules for the list of
- # helpers provided.
+ # * <tt>array</tt> - A normalized list of modules for the list of helpers provided.
def modules_for_helpers(args)
args += all_application_helpers if args.delete(:all)
super(args)
end
- # Extract helper names from files in app/helpers/**/*_helper.rb
+ # Extract helper names from files in <tt>app/helpers/**/*_helper.rb</tt>
def all_application_helpers
helpers = []
Array.wrap(helpers_path).each do |path|
@@ -1,8 +1,7 @@
require 'active_support/core_ext/class/attribute'
module ActionController
- # ActionController::HideActions adds the ability to prevent public methods on a controller
- # to be called as actions.
+ # Adds the ability to prevent public methods on a controller to be called as actions.
module HideActions
extend ActiveSupport::Concern
@@ -23,7 +22,7 @@ module ClassMethods
# Sets all of the actions passed in as hidden actions.
#
# ==== Parameters
- # *args<#to_s>:: A list of actions
+ # * <tt>args</tt> - A list of actions
def hide_action(*args)
self.hidden_actions = hidden_actions.dup.merge(args.map(&:to_s)).freeze
end
@@ -3,9 +3,9 @@
module ActionController
module HttpAuthentication
- # Makes it dead easy to do HTTP Basic authentication.
+ # Makes it dead easy to do HTTP \Basic and \Digest authentication.
#
- # Simple Basic example:
+ # === Simple \Basic example
#
# class PostsController < ApplicationController
# USER_NAME, PASSWORD = "dhh", "secret"
@@ -29,7 +29,9 @@ module HttpAuthentication
# end
#
#
- # Here is a more advanced Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
+ # === Advanced \Basic example
+ #
+ # Here is a more advanced \Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
# the regular HTML interface is protected by a session approach:
#
# class ApplicationController < ActionController::Base
@@ -69,7 +71,7 @@ module HttpAuthentication
# assert_equal 200, status
# end
#
- # Simple Digest example:
+ # === Simple \Digest example
#
# require 'digest/md5'
# class PostsController < ApplicationController
@@ -95,18 +97,20 @@ module HttpAuthentication
# end
# end
#
- # NOTE: The +authenticate_or_request_with_http_digest+ block must return the user's password or the ha1 digest hash so the framework can appropriately
- # hash to check the user's credentials. Returning +nil+ will cause authentication to fail.
- # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
- # the password file or database is compromised, the attacker would be able to use the ha1 hash to
- # authenticate as the user at this +realm+, but would not have the user's password to try using at
- # other sites.
+ # === Notes
+ #
+ # The +authenticate_or_request_with_http_digest+ block must return the user's password
+ # or the ha1 digest hash so the framework can appropriately hash to check the user's
+ # credentials. Returning +nil+ will cause authentication to fail.
#
- # On shared hosts, Apache sometimes doesn't pass authentication headers to
- # FCGI instances. If your environment matches this description and you cannot
- # authenticate, try this rule in your Apache setup:
+ # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
+ # the password file or database is compromised, the attacker would be able to use the ha1 hash to
+ # authenticate as the user at this +realm+, but would not have the user's password to try using at
+ # other sites.
#
- # RewriteRule ^(.*)$ dispatch.fcgi [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]
+ # In rare instances, web servers or front proxies strip authorization headers before
+ # they reach your application. You can debug this situation by logging all environment
+ # variables, and check for HTTP_AUTHORIZATION, amongst others.
module Basic
extend self
Oops, something went wrong.

0 comments on commit dda515f

Please sign in to comment.