Skip to content
This repository
Browse code

change rdoc to conform to api guidelines

  • Loading branch information...
commit eaeda503e89ac7f182d9a43a1917f5cc852cdb14 1 parent 111c4a4
Joost Baaij authored August 25, 2010
24  actionpack/lib/abstract_controller/base.rb
@@ -6,6 +6,10 @@ module AbstractController
6 6
   class Error < StandardError; end
7 7
   class ActionNotFound < StandardError; end
8 8
 
  9
+  # AbstractController is a low-level API. Nobody should be using it directly,
  10
+  # and subclasses of AbstractController (like ActionController::Base) are
  11
+  # expected to provide their own +render+ method, since rendering means
  12
+  # different things depending on the context.  
9 13
   class Base
10 14
     attr_internal :response_body
11 15
     attr_internal :action_name
@@ -41,8 +45,7 @@ def internal_methods
41 45
       # to specify particular actions as hidden.
42 46
       #
43 47
       # ==== Returns
44  
-      # Array[String]:: An array of method names that should not be
45  
-      #                 considered actions.
  48
+      # * <tt>Array</tt> - An array of method names that should not be considered actions.
46 49
       def hidden_actions
47 50
         []
48 51
       end
@@ -54,8 +57,7 @@ def hidden_actions
54 57
       # itself. Finally, #hidden_actions are removed.
55 58
       #
56 59
       # ==== Returns
57  
-      # Array[String]:: A list of all methods that should be considered
58  
-      #                 actions.
  60
+      # * <tt>Array</tt> - A list of all methods that should be considered actions.
59 61
       def action_methods
60 62
         @action_methods ||= begin
61 63
           # All public instance methods of this class, including ancestors
@@ -84,7 +86,7 @@ def clear_action_methods!
84 86
       # controller_name.
85 87
       #
86 88
       # ==== Returns
87  
-      # String
  89
+      # * <tt>String</tt>
88 90
       def controller_path
89 91
         @controller_path ||= name.sub(/Controller$/, '').underscore unless anonymous?
90 92
       end
@@ -104,7 +106,7 @@ def method_added(name)
104 106
     # ActionNotFound error is raised.
105 107
     #
106 108
     # ==== Returns
107  
-    # self
  109
+    # * <tt>self</tt>
108 110
     def process(action, *args)
109 111
       @_action_name = action_name = action.to_s
110 112
 
@@ -133,10 +135,10 @@ def action_methods
133 135
       # can be considered an action.
134 136
       #
135 137
       # ==== Parameters
136  
-      # name<String>:: The name of an action to be tested
  138
+      # * <tt>name</tt> - The name of an action to be tested
137 139
       #
138 140
       # ==== Returns
139  
-      # TrueClass, FalseClass
  141
+      # * <tt>TrueClass</tt>, <tt>FalseClass</tt>
140 142
       def action_method?(name)
141 143
         self.class.action_methods.include?(name)
142 144
       end
@@ -180,11 +182,11 @@ def _handle_action_missing
180 182
       # returns nil, an ActionNotFound exception will be raised.
181 183
       #
182 184
       # ==== Parameters
183  
-      # action_name<String>:: An action name to find a method name for
  185
+      # * <tt>action_name</tt> - An action name to find a method name for
184 186
       #
185 187
       # ==== Returns
186  
-      # String:: The name of the method that handles the action
187  
-      # nil::    No method name could be found. Raise ActionNotFound.
  188
+      # * <tt>String</tt> - The name of the method that handles the action
  189
+      # * <tt>nil</tt>    - No method name could be found. Raise ActionNotFound.
188 190
       def method_for_action(action_name)
189 191
         if action_method?(action_name) then action_name
190 192
         elsif respond_to?(:action_missing, true) then "_handle_action_missing"
45  actionpack/lib/abstract_controller/callbacks.rb
@@ -28,9 +28,8 @@ module ClassMethods
28 28
       # a Rails process.
29 29
       #
30 30
       # ==== Options
31  
-      # :only<#to_s>:: The callback should be run only for this action
32  
-      # :except<#to_s>:: The callback should be run for all actions
33  
-      #   except this action
  31
+      # * <tt>only</tt>   - The callback should be run only for this action
  32
+      # * <tt>except<tt>  - The callback should be run for all actions except this action
34 33
       def _normalize_callback_options(options)
35 34
         if only = options[:only]
36 35
           only = Array(only).map {|o| "action_name == '#{o}'"}.join(" || ")
@@ -45,7 +44,7 @@ def _normalize_callback_options(options)
45 44
       # Skip before, after, and around filters matching any of the names
46 45
       #
47 46
       # ==== Parameters
48  
-      # *names<Object>:: A list of valid names that could be used for
  47
+      # * <tt>names</tt> - A list of valid names that could be used for
49 48
       #   callbacks. Note that skipping uses Ruby equality, so it's
50 49
       #   impossible to skip a callback defined using an anonymous proc
51 50
       #   using #skip_filter
@@ -60,13 +59,13 @@ def skip_filter(*names, &blk)
60 59
       # the normalization across several methods that use it.
61 60
       #
62 61
       # ==== Parameters
63  
-      # callbacks<Array[*Object, Hash]>:: A list of callbacks, with an optional
  62
+      # * <tt>callbacks</tt> - An array of callbacks, with an optional
64 63
       #   options hash as the last parameter.
65  
-      # block<Proc>:: A proc that should be added to the callbacks.
  64
+      # * <tt>block</tt>    - A proc that should be added to the callbacks.
66 65
       #
67 66
       # ==== Block Parameters
68  
-      # name<Symbol>:: The callback to be added
69  
-      # options<Hash>:: A list of options to be used when adding the callback
  67
+      # * <tt>name</tt>     - The callback to be added
  68
+      # * <tt>options</tt>  - A hash of options to be used when adding the callback
70 69
       def _insert_callbacks(callbacks, block)
71 70
         options = callbacks.last.is_a?(Hash) ? callbacks.pop : {}
72 71
         _normalize_callback_options(options)
@@ -82,27 +81,27 @@ def _insert_callbacks(callbacks, block)
82 81
         class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
83 82
           # Append a before, after or around filter. See _insert_callbacks
84 83
           # for details on the allowed parameters.
85  
-          def #{filter}_filter(*names, &blk)
86  
-            _insert_callbacks(names, blk) do |name, options|
87  
-              set_callback(:process_action, :#{filter}, name, options)
88  
-            end
89  
-          end
  84
+          def #{filter}_filter(*names, &blk)                                                    # def before_filter(*names, &blk)
  85
+            _insert_callbacks(names, blk) do |name, options|                                    #   _insert_callbacks(names, blk) do |name, options}
  86
+              set_callback(:process_action, :#{filter}, name, options)                          #     set_callback(:process_action, :before_filter, name, options)
  87
+            end                                                                                 #   end
  88
+          end                                                                                   # end
90 89
 
91 90
           # Prepend a before, after or around filter. See _insert_callbacks
92 91
           # for details on the allowed parameters.
93  
-          def prepend_#{filter}_filter(*names, &blk)
94  
-            _insert_callbacks(names, blk) do |name, options|
95  
-              set_callback(:process_action, :#{filter}, name, options.merge(:prepend => true))
96  
-            end
97  
-          end
  92
+          def prepend_#{filter}_filter(*names, &blk)                                            # def prepend_before_filter(*names, &blk)
  93
+            _insert_callbacks(names, blk) do |name, options|                                    #   _insert_callbacks(names, blk) do |name, options|
  94
+              set_callback(:process_action, :#{filter}, name, options.merge(:prepend => true))  #     set_callback(:process_action, :before, name, options.merge(:prepend => true))
  95
+            end                                                                                 #   end
  96
+          end                                                                                   # end
98 97
 
99 98
           # Skip a before, after or around filter. See _insert_callbacks
100 99
           # for details on the allowed parameters.
101  
-          def skip_#{filter}_filter(*names, &blk)
102  
-            _insert_callbacks(names, blk) do |name, options|
103  
-              skip_callback(:process_action, :#{filter}, name, options)
104  
-            end
105  
-          end
  100
+          def skip_#{filter}_filter(*names, &blk)                                               # def skip_before_filter(*names, &blk)
  101
+            _insert_callbacks(names, blk) do |name, options|                                    #   _insert_callbacks(names, blk) do |name, options|
  102
+              skip_callback(:process_action, :#{filter}, name, options)                         #     skip_callback(:process_action, :before, name, options)
  103
+            end                                                                                 #   end
  104
+          end                                                                                   # end
106 105
 
107 106
           # *_filter is the same as append_*_filter
108 107
           alias_method :append_#{filter}_filter, :#{filter}_filter
12  actionpack/lib/abstract_controller/helpers.rb
@@ -40,7 +40,7 @@ def inherited(klass)
40 40
       #  <% if logged_in? -%>Welcome, <%= current_user.name %><% end -%>
41 41
       #
42 42
       # ==== Parameters
43  
-      # meths<Array[#to_s]>:: The name of a method on the controller
  43
+      # * <tt>method[, method]</tt> - A name or names of a method on the controller
44 44
       #   to be made available on the view.
45 45
       def helper_method(*meths)
46 46
         meths.flatten.each do |meth|
@@ -55,8 +55,8 @@ def #{meth}(*args, &blk)
55 55
       # The +helper+ class method can take a series of helper module names, a block, or both.
56 56
       #
57 57
       # ==== Parameters
58  
-      # *args<Array[Module, Symbol, String, :all]>
59  
-      # block<Block>:: A block defining helper methods
  58
+      # * <tt>*args</tt> - Module, Symbol, String, :all
  59
+      # * <tt>block</tt> - A block defining helper methods
60 60
       #
61 61
       # ==== Examples
62 62
       # When the argument is a module it will be included directly in the template class.
@@ -100,7 +100,7 @@ def helper(*args, &block)
100 100
       # rendered through this controller.
101 101
       #
102 102
       # ==== Parameters
103  
-      # mod<Module>:: The module to include into the current helper module
  103
+      # * <tt>module</tt> - The module to include into the current helper module
104 104
       #   for the class
105 105
       def add_template_helper(mod)
106 106
         _helpers.module_eval { include mod }
@@ -118,10 +118,10 @@ def add_template_helper(mod)
118 118
       # are returned.
119 119
       #
120 120
       # ==== Parameters
121  
-      # args<Array[String, Symbol, Module]>:: A list of helpers
  121
+      # * <tt>args</tt> - An array of helpers
122 122
       #
123 123
       # ==== Returns
124  
-      # Array[Module]:: A normalized list of modules for the list of
  124
+      # * <tt>Array</tt> - A normalized list of modules for the list of
125 125
       #   helpers provided.
126 126
       def modules_for_helpers(args)
127 127
         args.flatten.map! do |arg|
22  actionpack/lib/abstract_controller/layouts.rb
@@ -114,11 +114,13 @@ module AbstractController
114 114
   #
115 115
   #   class WeblogController < ActionController::Base
116 116
   #     layout proc{ |controller| controller.logged_in? ? "writer_layout" : "reader_layout" }
  117
+  #   end
117 118
   #
118 119
   # Of course, the most common way of specifying a layout is still just as a plain template name:
119 120
   #
120 121
   #   class WeblogController < ActionController::Base
121 122
   #     layout "weblog_standard"
  123
+  #   end
122 124
   #
123 125
   # If no directory is specified for the template name, the template will by default be looked for in <tt>app/views/layouts/</tt>.
124 126
   # Otherwise, it will be looked up relative to the template root.
@@ -183,7 +185,7 @@ module LayoutConditions
183 185
         # layout.
184 186
         #
185 187
         # ==== Returns
186  
-        # Boolean:: True if the action has a layout, false otherwise.
  188
+        # * <tt> Boolean</tt> - True if the action has a layout, false otherwise.
187 189
         def action_has_layout?
188 190
           return unless super
189 191
 
@@ -209,11 +211,11 @@ def action_has_layout?
209 211
       # true::   raise an ArgumentError
210 212
       #
211 213
       # ==== Parameters
212  
-      # layout<String, Symbol, false)>:: The layout to use.
  214
+      # * <tt>String, Symbol, false</tt> - The layout to use.
213 215
       #
214 216
       # ==== Options (conditions)
215  
-      # :only<#to_s, Array[#to_s]>:: A list of actions to apply this layout to.
216  
-      # :except<#to_s, Array[#to_s]>:: Apply this layout to all actions but this one
  217
+      # * :only   - A list of actions to apply this layout to.
  218
+      # * :except - Apply this layout to all actions but this one.
217 219
       def layout(layout, conditions = {})
218 220
         include LayoutConditions unless conditions.empty?
219 221
 
@@ -228,7 +230,7 @@ def layout(layout, conditions = {})
228 230
       # value of this method.
229 231
       #
230 232
       # ==== Returns
231  
-      # String:: A template name
  233
+      # * <tt>String</tt> - A template name
232 234
       def _implied_layout_name
233 235
         controller_path
234 236
       end
@@ -313,8 +315,8 @@ def _layout; end
313 315
     # the name type.
314 316
     #
315 317
     # ==== Parameters
316  
-    # name<String|TrueClass|FalseClass|Symbol>:: The name of the template
317  
-    # details<Hash{Symbol => Object}>:: A list of details to restrict
  318
+    # * <tt>name</tt> - The name of the template
  319
+    # * <tt>details</tt> - A list of details to restrict
318 320
     #   the lookup to. By default, layout lookup is limited to the
319 321
     #   formats specified for the current request.
320 322
     def _layout_for_option(name)
@@ -333,14 +335,14 @@ def _layout_for_option(name)
333 335
     # Optionally raises an exception if the layout could not be found.
334 336
     #
335 337
     # ==== Parameters
336  
-    # details<Hash>:: A list of details to restrict the search by. This
  338
+    # * <tt>details</tt> - A list of details to restrict the search by. This
337 339
     #   might include details like the format or locale of the template.
338  
-    # require_layout<Boolean>:: If this is true, raise an ArgumentError
  340
+    # * <tt>require_logout</tt> - If this is true, raise an ArgumentError
339 341
     #   with details about the fact that the exception could not be
340 342
     #   found (defaults to false)
341 343
     #
342 344
     # ==== Returns
343  
-    # Template:: The template object for the default layout (or nil)
  345
+    # * <tt>template</tt> - The template object for the default layout (or nil)
344 346
     def _default_layout(require_layout = false)
345 347
       begin
346 348
         layout_name = _layout if action_has_layout?
14  actionpack/lib/abstract_controller/view_paths.rb
@@ -34,9 +34,9 @@ module ClassMethods
34 34
       # Append a path to the list of view paths for this controller.
35 35
       #
36 36
       # ==== Parameters
37  
-      # path<String, ViewPath>:: If a String is provided, it gets converted into
38  
-      # the default view path. You may also provide a custom view path
39  
-      # (see ActionView::ViewPathSet for more information)
  37
+      # * <tt>path</tt> - If a String is provided, it gets converted into
  38
+      #   the default view path. You may also provide a custom view path
  39
+      #   (see ActionView::ViewPathSet for more information)
40 40
       def append_view_path(path)
41 41
         self.view_paths = view_paths.dup + Array(path)
42 42
       end
@@ -44,9 +44,9 @@ def append_view_path(path)
44 44
       # Prepend a path to the list of view paths for this controller.
45 45
       #
46 46
       # ==== Parameters
47  
-      # path<String, ViewPath>:: If a String is provided, it gets converted into
48  
-      # the default view path. You may also provide a custom view path
49  
-      # (see ActionView::ViewPathSet for more information)
  47
+      # * <tt>path</tt> - If a String is provided, it gets converted into
  48
+      #   the default view path. You may also provide a custom view path
  49
+      #   (see ActionView::ViewPathSet for more information)
50 50
       def prepend_view_path(path)
51 51
         self.view_paths = Array(path) + view_paths.dup
52 52
       end
@@ -59,7 +59,7 @@ def view_paths
59 59
       # Set the view paths.
60 60
       #
61 61
       # ==== Parameters
62  
-      # paths<ViewPathSet, Object>:: If a ViewPathSet is provided, use that;
  62
+      # * <tt>paths</tt> - If a ViewPathSet is provided, use that;
63 63
       #   otherwise, process the parameter into a ViewPathSet.
64 64
       def view_paths=(paths)
65 65
         self._view_paths = ActionView::Base.process_view_paths(paths)

0 notes on commit eaeda50

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