Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

cleanup of ActionController::Metal inline documentation

  • Loading branch information...
commit ca36326706edc6cc2ceffa18d093ba799cc65caf 1 parent 9301029
@tilsammans tilsammans authored
View
28 actionpack/lib/action_controller/metal.rb
@@ -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,8 +125,7 @@ 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
@@ -134,8 +133,7 @@ def dispatch(name, request)
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))
View
12 actionpack/lib/action_controller/metal/conditional_get.rb
@@ -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)
View
24 actionpack/lib/action_controller/metal/helpers.rb
@@ -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|
View
5 actionpack/lib/action_controller/metal/hide_actions.rb
@@ -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
View
32 actionpack/lib/action_controller/metal/http_authentication.rb
@@ -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

0 comments on commit ca36326

Please sign in to comment.
Something went wrong with that request. Please try again.