Skip to content
This repository
Browse code

cleanup of ActionController::Metal inline documentation

  • Loading branch information...
commit ca36326706edc6cc2ceffa18d093ba799cc65caf 1 parent 9301029
Joost Baaij authored August 26, 2010
28  actionpack/lib/action_controller/metal.rb
@@ -43,28 +43,28 @@ def build(action, app=nil, &block)
43 43
     end
44 44
   end
45 45
 
46  
-  # ActionController::Metal provides a way to get a valid Rack application from a controller.
  46
+  # Provides a way to get a valid Rack application from a controller.
47 47
   #
48 48
   # In AbstractController, dispatching is triggered directly by calling #process on a new controller.
49  
-  # ActionController::Metal provides an #action method that returns a valid Rack application for a
50  
-  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the Rails router,
51  
-  # can dispatch directly to the action returned by FooController.action(:index).
  49
+  # <tt>ActionController::Metal</tt> provides an <tt>action</tt> method that returns a valid Rack application for a
  50
+  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the \Rails router,
  51
+  # can dispatch directly to actions returned by controllers in your application.
52 52
   class Metal < AbstractController::Base
53 53
     abstract!
54 54
 
55 55
     attr_internal :env
56 56
 
57 57
     # Returns the last part of the controller's name, underscored, without the ending
58  
-    # "Controller". For instance, MyApp::MyPostsController would return "my_posts" for
59  
-    # controller_name
  58
+    # <tt>Controller</tt>. For instance, PostsController returns <tt>posts</tt>.
  59
+    # Namespaces are left out, so Admin::PostsController returns <tt>posts</tt> as well.
60 60
     #
61 61
     # ==== Returns
62  
-    # String
  62
+    # * <tt>string</tt>
63 63
     def self.controller_name
64 64
       @controller_name ||= self.name.demodulize.sub(/Controller$/, '').underscore
65 65
     end
66 66
 
67  
-    # Delegates to the class' #controller_name
  67
+    # Delegates to the class' <tt>controller_name</tt>
68 68
     def controller_name
69 69
       self.class.controller_name
70 70
     end
@@ -95,7 +95,7 @@ def params=(val)
95 95
     # Basic implementations for content_type=, location=, and headers are
96 96
     # provided to reduce the dependency on the RackDelegation module
97 97
     # in Renderer and Redirector.
98  
-
  98
+    
99 99
     def content_type=(type)
100 100
       headers["Content-Type"] = type.to_s
101 101
     end
@@ -125,8 +125,7 @@ def response_body=(val)
125 125
       super body
126 126
     end
127 127
 
128  
-    # :api: private
129  
-    def dispatch(name, request)
  128
+    def dispatch(name, request) #:nodoc:
130 129
       @_request = request
131 130
       @_env = request.env
132 131
       @_env['action_controller.instance'] = self
@@ -134,8 +133,7 @@ def dispatch(name, request)
134 133
       to_a
135 134
     end
136 135
 
137  
-    # :api: private
138  
-    def to_a
  136
+    def to_a #:nodoc:
139 137
       response ? response.to_a : [status, headers, response_body]
140 138
     end
141 139
 
@@ -164,10 +162,10 @@ def self.call(env)
164 162
     # for the same action.
165 163
     #
166 164
     # ==== Parameters
167  
-    # action<#to_s>:: An action name
  165
+    # * <tt>action</tt> - An action name
168 166
     #
169 167
     # ==== Returns
170  
-    # Proc:: A rack application
  168
+    # * <tt>proc</tt> - A rack application
171 169
     def self.action(name, klass = ActionDispatch::Request)
172 170
       middleware_stack.build(name.to_s) do |env|
173 171
         new.dispatch(name, klass.new(env))
12  actionpack/lib/action_controller/metal/conditional_get.rb
@@ -6,7 +6,7 @@ module ConditionalGet
6 6
     include Head
7 7
 
8 8
     # Sets the etag, last_modified, or both on the response and renders a
9  
-    # "304 Not Modified" response if the request is already fresh.
  9
+    # <tt>304 Not Modified</tt> response if the request is already fresh.
10 10
     #
11 11
     # Parameters:
12 12
     # * <tt>:etag</tt>
@@ -21,7 +21,7 @@ module ConditionalGet
21 21
     #   end
22 22
     #
23 23
     # This will render the show template if the request isn't sending a matching etag or
24  
-    # If-Modified-Since header and just a "304 Not Modified" response if there's a match.
  24
+    # If-Modified-Since header and just a <tt>304 Not Modified</tt> response if there's a match.
25 25
     #
26 26
     def fresh_when(options)
27 27
       options.assert_valid_keys(:etag, :last_modified, :public)
@@ -36,7 +36,7 @@ def fresh_when(options)
36 36
     # Sets the etag and/or last_modified on the response and checks it against
37 37
     # the client request. If the request doesn't match the options provided, the
38 38
     # request is considered stale and should be generated from scratch. Otherwise,
39  
-    # it's fresh and we don't need to generate anything and a reply of "304 Not Modified" is sent.
  39
+    # it's fresh and we don't need to generate anything and a reply of <tt>304 Not Modified</tt> is sent.
40 40
     #
41 41
     # Parameters:
42 42
     # * <tt>:etag</tt>
@@ -60,8 +60,8 @@ def stale?(options)
60 60
       !request.fresh?(response)
61 61
     end
62 62
 
63  
-    # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a "private" instruction, so that
64  
-    # intermediate caches shouldn't cache the response.
  63
+    # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a <tt>private</tt> instruction, so that
  64
+    # intermediate caches must not cache the response.
65 65
     #
66 66
     # Examples:
67 67
     #   expires_in 20.minutes
@@ -77,7 +77,7 @@ def expires_in(seconds, options = {}) #:doc:
77 77
       response.cache_control[:extras] = options.map {|k,v| "#{k}=#{v}"}
78 78
     end
79 79
 
80  
-    # Sets a HTTP 1.1 Cache-Control header of "no-cache" so no caching should occur by the browser or
  80
+    # Sets a HTTP 1.1 Cache-Control header of <tt>no-cache</tt> so no caching should occur by the browser or
81 81
     # intermediate caches (like caching proxy servers).
82 82
     def expires_now #:doc:
83 83
       response.cache_control.replace(:no_cache => true)
24  actionpack/lib/action_controller/metal/helpers.rb
@@ -2,21 +2,21 @@
2 2
 require 'active_support/core_ext/class/attribute'
3 3
 
4 4
 module ActionController
5  
-  # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+,
6  
-  # +numbers+ and model objects, to name a few. These helpers are available to all templates
  5
+  # The \Rails framework provides a large number of helpers for working with assets, dates, forms,
  6
+  # numbers and model objects, to name a few. These helpers are available to all templates
7 7
   # by default.
8 8
   #
9  
-  # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to
  9
+  # In addition to using the standard template helpers provided, creating custom helpers to
10 10
   # extract complicated logic or reusable functionality is strongly encouraged. By default, the controller will
11 11
   # include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically
12 12
   # include <tt>MyHelper</tt>.
13 13
   #
14  
-  # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any
  14
+  # Additional helpers can be specified using the +helper+ class method in ActionController::Base or any
15 15
   # controller which inherits from it.
16 16
   #
17 17
   # ==== Examples
18  
-  # The +to_s+ method from the Time class can be wrapped in a helper method to display a custom message if
19  
-  # the Time object is blank:
  18
+  # The +to_s+ method from the \Time class can be wrapped in a helper method to display a custom message if
  19
+  # a \Time object is blank:
20 20
   #
21 21
   #   module FormattedTimeHelper
22 22
   #     def format_time(time, format=:long, blank_message="&nbsp;")
@@ -71,12 +71,11 @@ def helpers_dir=(value)
71 71
       # Declares helper accessors for controller attributes. For example, the
72 72
       # following adds new +name+ and <tt>name=</tt> instance methods to a
73 73
       # controller and makes them available to the view:
74  
-      #   helper_attr :name
75 74
       #   attr_accessor :name
  75
+      #   helper_attr :name
76 76
       #
77 77
       # ==== Parameters
78  
-      # *attrs<Array[String, Symbol]>:: Names of attributes to be converted
79  
-      #   into helpers.
  78
+      # * <tt>attrs</tt> - Names of attributes to be converted into helpers.
80 79
       def helper_attr(*attrs)
81 80
         attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
82 81
       end
@@ -91,17 +90,16 @@ def helpers
91 90
         # all helpers in helpers_dir.
92 91
         #
93 92
         # ==== Parameters
94  
-        # args<Array[String, Symbol, Module, all]>:: A list of helpers
  93
+        # * <tt>args</tt> - A list of helpers
95 94
         #
96 95
         # ==== Returns
97  
-        # Array[Module]:: A normalized list of modules for the list of
98  
-        #   helpers provided.
  96
+        # * <tt>array</tt> - A normalized list of modules for the list of helpers provided.
99 97
         def modules_for_helpers(args)
100 98
           args += all_application_helpers if args.delete(:all)
101 99
           super(args)
102 100
         end
103 101
 
104  
-        # Extract helper names from files in app/helpers/**/*_helper.rb
  102
+        # Extract helper names from files in <tt>app/helpers/**/*_helper.rb</tt>
105 103
         def all_application_helpers
106 104
           helpers = []
107 105
           Array.wrap(helpers_path).each do |path|
5  actionpack/lib/action_controller/metal/hide_actions.rb
... ...
@@ -1,8 +1,7 @@
1 1
 require 'active_support/core_ext/class/attribute'
2 2
 
3 3
 module ActionController
4  
-  # ActionController::HideActions adds the ability to prevent public methods on a controller
5  
-  # to be called as actions.
  4
+  # Adds the ability to prevent public methods on a controller to be called as actions.
6 5
   module HideActions
7 6
     extend ActiveSupport::Concern
8 7
 
@@ -23,7 +22,7 @@ module ClassMethods
23 22
       # Sets all of the actions passed in as hidden actions.
24 23
       #
25 24
       # ==== Parameters
26  
-      # *args<#to_s>:: A list of actions
  25
+      # * <tt>args</tt> - A list of actions
27 26
       def hide_action(*args)
28 27
         self.hidden_actions = hidden_actions.dup.merge(args.map(&:to_s)).freeze
29 28
       end
32  actionpack/lib/action_controller/metal/http_authentication.rb
@@ -3,9 +3,9 @@
3 3
 
4 4
 module ActionController
5 5
   module HttpAuthentication
6  
-    # Makes it dead easy to do HTTP Basic authentication.
  6
+    # Makes it dead easy to do HTTP \Basic and \Digest authentication.
7 7
     #
8  
-    # Simple Basic example:
  8
+    # === Simple \Basic example
9 9
     #
10 10
     #   class PostsController < ApplicationController
11 11
     #     USER_NAME, PASSWORD = "dhh", "secret"
@@ -29,7 +29,9 @@ module HttpAuthentication
29 29
     #   end
30 30
     #
31 31
     #
32  
-    # Here is a more advanced Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
  32
+    # === Advanced \Basic example
  33
+    # 
  34
+    # Here is a more advanced \Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
33 35
     # the regular HTML interface is protected by a session approach:
34 36
     #
35 37
     #   class ApplicationController < ActionController::Base
@@ -69,7 +71,7 @@ module HttpAuthentication
69 71
     #     assert_equal 200, status
70 72
     #   end
71 73
     #
72  
-    # Simple Digest example:
  74
+    # === Simple \Digest example
73 75
     #
74 76
     #   require 'digest/md5'
75 77
     #   class PostsController < ApplicationController
@@ -95,18 +97,20 @@ module HttpAuthentication
95 97
     #       end
96 98
     #   end
97 99
     #
98  
-    # 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
99  
-    #       hash to check the user's credentials. Returning +nil+ will cause authentication to fail.
100  
-    #       Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
101  
-    #       the password file or database is compromised, the attacker would be able to use the ha1 hash to
102  
-    #       authenticate as the user at this +realm+, but would not have the user's password to try using at
103  
-    #       other sites.
  100
+    # === Notes
  101
+    # 
  102
+    # The +authenticate_or_request_with_http_digest+ block must return the user's password
  103
+    # or the ha1 digest hash so the framework can appropriately hash to check the user's
  104
+    # credentials. Returning +nil+ will cause authentication to fail.
104 105
     #
105  
-    # On shared hosts, Apache sometimes doesn't pass authentication headers to
106  
-    # FCGI instances. If your environment matches this description and you cannot
107  
-    # authenticate, try this rule in your Apache setup:
  106
+    # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
  107
+    # the password file or database is compromised, the attacker would be able to use the ha1 hash to
  108
+    # authenticate as the user at this +realm+, but would not have the user's password to try using at
  109
+    # other sites.
108 110
     #
109  
-    #   RewriteRule ^(.*)$ dispatch.fcgi [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]
  111
+    # In rare instances, web servers or front proxies strip authorization headers before
  112
+    # they reach your application. You can debug this situation by logging all environment
  113
+    # variables, and check for HTTP_AUTHORIZATION, amongst others.
110 114
     module Basic
111 115
       extend self
112 116
 

0 notes on commit ca36326

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