Make conditional_layout? private and update documentation

The conditional_layout? method is not for public use and doesn't
actually do what the documentation suggested it does. It's actually
used to determine whether or not to use the explicit layout definition
defined in a controller or use the implicit layout definition.

Also documentation was added for the action_has_layout? method which
acts as a master switch for disabling the layout for the current
action. This method was added so that action caching didn't depend
on accessing layout internals but is also used by third-parties,
most notably the [Hobo][1] application.

[1]: https://github.com/hobo/hobo

1 files changed, 23 insertions, 15 deletions

diff --git a/actionpack/lib/abstract_controller/layouts.rb b/actionpack/lib/abstract_controller/layouts.rb
index 12da273af9..73799e8085 100644
--- a/actionpack/lib/abstract_controller/layouts.rb
+++ b/actionpack/lib/abstract_controller/layouts.rb
@@ -212,21 +212,23 @@ module AbstractController
     delegate :_layout_conditions, :to => "self.class"
 
     module ClassMethods
-      def inherited(klass)
+      def inherited(klass) # :nodoc:
         super
         klass._write_layout_method
       end
 
       # This module is mixed in if layout conditions are provided. This means
       # that if no layout conditions are used, this method is not used
-      module LayoutConditions
-        # Determines whether the current action has a layout by checking the
-        # action name against the :only and :except conditions set on the
-        # layout.
+      module LayoutConditions # :nodoc:
+      private
+
+        # Determines whether the current action has a layout definition by
+        # checking the action name against the :only and :except conditions
+        # set by the <tt>layout</tt> method.
         #
         # ==== Returns
-        # * <tt> Boolean</tt> - True if the action has a layout, false otherwise.
-        def conditional_layout?
+        # * <tt> Boolean</tt> - True if the action has a layout definition, false otherwise.
+        def _conditional_layout?
           return unless super
 
           conditions = _layout_conditions
@@ -271,7 +273,7 @@ module AbstractController
       #
       # ==== Returns
       # * <tt>String</tt> - A template name
-      def _implied_layout_name
+      def _implied_layout_name # :nodoc:
         controller_path
       end
 
@@ -279,7 +281,7 @@ module AbstractController
       #
       # If a layout is not explicitly mentioned then look for a layout with the controller's name.
       # if nothing is found then try same procedure to find super class's layout.
-      def _write_layout_method
+      def _write_layout_method # :nodoc:
         remove_possible_method(:_layout)
 
         prefixes    = _implied_layout_name =~ /\blayouts/ ? [] : ["layouts"]
@@ -318,7 +320,7 @@ module AbstractController
 
         self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def _layout
-            if conditional_layout?
+            if _conditional_layout?
               #{layout_definition}
             else
               #{name_clause}
@@ -329,7 +331,7 @@ module AbstractController
       end
     end
 
-    def _normalize_options(options)
+    def _normalize_options(options) # :nodoc:
       super
 
       if _include_layout?(options)
@@ -340,21 +342,27 @@ module AbstractController
 
     attr_internal_writer :action_has_layout
 
-    def initialize(*)
+    def initialize(*) # :nodoc:
       @_action_has_layout = true
       super
     end
 
+    # Controls whether an action should be rendered using a layout.
+    # If you want to disable any <tt>layout</tt> settings for the
+    # current action so that it is rendered without a layout then
+    # either override this method in your controller to return false
+    # for that action or set the <tt>action_has_layout</tt> attribute
+    # to false before rendering.
     def action_has_layout?
       @_action_has_layout
     end
 
-    def conditional_layout?
+  private
+
+    def _conditional_layout?
       true
     end
 
-  private
-
     # This will be overwritten by _write_layout_method
     def _layout; end