Configuration#prepare docs cleanup. Ref #58

README.md

@@ -959,13 +959,17 @@ Lotus::Controller.configure do
   #
   format custom: 'application/custom'
 
-  # Configure the modules to be included/extended/prepended by default.
-  # Argument: proc, empty by default
+  # Configure the logic to be executed when Lotus::Action is included
+  # This is useful to DRY code by having a single place where to configure
+  # shared behaviors like authentication, sessions, cookies etc.
+  # Argument: proc
   #
   prepare do
     include Lotus::Action::Sessions
-    using SomeMiddleWare
-    prepend MyLibrary::Session::Store
+    include MyAuthentication
+    use SomeMiddleWare
+
+    before { authenticate! }
   end
 end
 ```

lib/lotus/controller/configuration.rb

@@ -273,46 +273,42 @@ def action_module(value = nil)
         end
       end
 
-      # Specify the default modules to be included when `Lotus::Action` (or the
-      # `action_module`) is included.
+      # Configure the logic to be executed when Lotus::Action is included
+      # This is useful to DRY code by having a single place where to configure
+      # shared behaviors like authentication, sessions, cookies etc.
       #
-      # If not set, this option will be ignored.
+      # This method can be called multiple times.
       #
-      # This is part of a DSL, for this reason when this method is called with
-      # an argument, it will set the corresponding instance variable.
-      #
-      # @overload prepare(blk)
-      #   Adds the given block
-      #   @param value [Proc] the included block
+      # @param blk [Proc] the code block
       #
-      # @since 0.2.0
+      # @return [void]
       #
-      # @see Lotus::Controller#duplicate
+      # @raise [ArgumentError] if called without passing a block
       #
-      # @example Getting the value
-      #   require 'lotus/controller'
+      # @since 0.3.0
       #
-      #   Lotus::Controller.configuration.modules # => []
+      # @see Lotus::Controller.configure
+      # @see Lotus::Controller.duplicate
       #
-      # @example Setting the value
+      # @example Configure shared logic.
       #   require 'lotus/controller'
-      #   require 'lotus/action/cookies'
-      #   require 'lotus/action/session'
       #
       #   Lotus::Controller.configure do
       #     prepare do
-      #       include Lotus::Action::Cookies
-      #       include Lotus::Action::Session
-      #       before { do_something }
+      #       include Lotus::Action::Sessions
+      #       include MyAuthentication
+      #       use SomeMiddleWare
+      #
+      #       before { authenticate! }
       #     end
       #   end
       #
       #   module Dashboard
       #     class Index
-      #       # It includes:
-      #       #   * Lotus::Action
-      #       #   * Lotus::Action::Cookies
-      #       #   * Lotus::Action::Session
+      #       # When Lotus::Action is included, it will:
+      #       #   * Include `Lotus::Action::Session` and `MyAuthentication`
+      #       #   * Configure to use `SomeMiddleWare`
+      #       #   * Configure a `before` callback that triggers `#authenticate!`
       #       include Lotus::Action
       #
       #       def call(params)
@@ -324,7 +320,7 @@ def prepare(&blk)
         if block_given?
           @modules.push(blk)
         else
-          raise ArgumentError.new('Please provide a proc or a block')
+          raise ArgumentError.new('Please provide a block')
         end
       end
 

test/configuration_test.rb

@@ -117,7 +117,7 @@ def status
     describe 'when prepare with no block' do
       it 'raises error' do
         exception = -> { @configuration.prepare }.must_raise(ArgumentError)
-        exception.message.must_equal 'Please provide a proc or a block'
+        exception.message.must_equal 'Please provide a block'
       end
 
     end