From ca36326706edc6cc2ceffa18d093ba799cc65caf Mon Sep 17 00:00:00 2001 From: Joost Baaij Date: Thu, 26 Aug 2010 22:32:40 +0200 Subject: cleanup of ActionController::Metal inline documentation --- actionpack/lib/action_controller/metal.rb | 28 +++++++++---------- .../lib/action_controller/metal/conditional_get.rb | 12 ++++---- actionpack/lib/action_controller/metal/helpers.rb | 24 ++++++++-------- .../lib/action_controller/metal/hide_actions.rb | 5 ++-- .../action_controller/metal/http_authentication.rb | 32 ++++++++++++---------- 5 files changed, 50 insertions(+), 51 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_controller/metal.rb b/actionpack/lib/action_controller/metal.rb index 2281c500c5..96ac138ba3 100644 --- a/actionpack/lib/action_controller/metal.rb +++ b/actionpack/lib/action_controller/metal.rb @@ -43,28 +43,28 @@ module ActionController 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). + # 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 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 + # Controller. For instance, PostsController returns posts. + # Namespaces are left out, so Admin::PostsController returns posts as well. # # ==== Returns - # String + # * string def self.controller_name @controller_name ||= self.name.demodulize.sub(/Controller$/, '').underscore end - # Delegates to the class' #controller_name + # Delegates to the class' controller_name def controller_name self.class.controller_name end @@ -95,7 +95,7 @@ module ActionController # 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 @@ module ActionController 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 @@ module ActionController 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 @@ module ActionController # for the same action. # # ==== Parameters - # action<#to_s>:: An action name + # * action - An action name # # ==== Returns - # Proc:: A rack application + # * proc - A rack application def self.action(name, klass = ActionDispatch::Request) middleware_stack.build(name.to_s) do |env| new.dispatch(name, klass.new(env)) diff --git a/actionpack/lib/action_controller/metal/conditional_get.rb b/actionpack/lib/action_controller/metal/conditional_get.rb index 61e7ece90d..797ad846f6 100644 --- a/actionpack/lib/action_controller/metal/conditional_get.rb +++ b/actionpack/lib/action_controller/metal/conditional_get.rb @@ -6,7 +6,7 @@ module ActionController 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. + # 304 Not Modified response if the request is already fresh. # # Parameters: # * :etag @@ -21,7 +21,7 @@ module ActionController # 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 304 Not Modified response if there's a match. # def fresh_when(options) options.assert_valid_keys(:etag, :last_modified, :public) @@ -36,7 +36,7 @@ module ActionController # 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 304 Not Modified is sent. # # Parameters: # * :etag @@ -60,8 +60,8 @@ module ActionController !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 private instruction, so that + # intermediate caches must not cache the response. # # Examples: # expires_in 20.minutes @@ -77,7 +77,7 @@ module ActionController 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 no-cache 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) diff --git a/actionpack/lib/action_controller/metal/helpers.rb b/actionpack/lib/action_controller/metal/helpers.rb index e0bc47318a..4b6897c5dd 100644 --- a/actionpack/lib/action_controller/metal/helpers.rb +++ b/actionpack/lib/action_controller/metal/helpers.rb @@ -2,21 +2,21 @@ require 'active_support/core_ext/array/wrap' 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., MyController will automatically # include MyHelper. # - # Additional helpers can be specified using the +helper+ class method in ActionController::Base 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=" ") @@ -71,12 +71,11 @@ module ActionController # Declares helper accessors for controller attributes. For example, the # following adds new +name+ and name= instance methods to a # controller and makes them available to the view: - # helper_attr :name # attr_accessor :name + # helper_attr :name # # ==== Parameters - # *attrs:: Names of attributes to be converted - # into helpers. + # * attrs - 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 @@ module ActionController # all helpers in helpers_dir. # # ==== Parameters - # args:: A list of helpers + # * args - A list of helpers # # ==== Returns - # Array[Module]:: A normalized list of modules for the list of - # helpers provided. + # * array - 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 app/helpers/**/*_helper.rb def all_application_helpers helpers = [] Array.wrap(helpers_path).each do |path| diff --git a/actionpack/lib/action_controller/metal/hide_actions.rb b/actionpack/lib/action_controller/metal/hide_actions.rb index 32d7a96701..b55c4643be 100644 --- a/actionpack/lib/action_controller/metal/hide_actions.rb +++ b/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 ActionController # Sets all of the actions passed in as hidden actions. # # ==== Parameters - # *args<#to_s>:: A list of actions + # * args - A list of actions def hide_action(*args) self.hidden_actions = hidden_actions.dup.merge(args.map(&:to_s)).freeze end diff --git a/actionpack/lib/action_controller/metal/http_authentication.rb b/actionpack/lib/action_controller/metal/http_authentication.rb index acd313b039..1d74521e4f 100644 --- a/actionpack/lib/action_controller/metal/http_authentication.rb +++ b/actionpack/lib/action_controller/metal/http_authentication.rb @@ -3,9 +3,9 @@ require 'active_support/core_ext/object/blank' 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 ActionController # 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 ActionController # assert_equal 200, status # end # - # Simple Digest example: + # === Simple \Digest example # # require 'digest/md5' # class PostsController < ApplicationController @@ -95,18 +97,20 @@ module ActionController # 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 -- cgit v1.2.3