Improve documentation for after_sign_in_path_for.

README.rdoc

@@ -48,7 +48,9 @@ Run the generator:
 
 	ruby script/generate devise_install
 
-And you're ready to go. The generator will install an initializer which describes Devise's configuration options. Be sure to take a look.
+And you're ready to go. The generator will install an initializer which describes ALL Devise's configuration options, so be sure to take a look at it and the documentation as well:
+
+  http://rdoc.info/projects/plataformatec/devise
 
 == Basic Usage
 

app/controllers/sessions_controller.rb

@@ -14,9 +14,9 @@ def new
 
   # POST /resource/sign_in
   def create
-    if authenticate(resource_name)
+    if resource = authenticate(resource_name)
       set_flash_message :success, :signed_in
-      sign_in_and_redirect(resource_name)
+      sign_in_and_redirect(resource_name, resource, true)
     else
       set_now_flash_message :failure, warden.message || :invalid
       build_resource

lib/devise/controllers/helpers.rb

@@ -57,7 +57,7 @@ def signed_in?(scope)
       #   sign_in @user           # sign_in(resource)
       #
       def sign_in(resource_or_scope, resource=nil)
-        scope    ||= Devise::Mapping.find_scope!(resource_or_scope)
+        scope      = Devise::Mapping.find_scope!(resource_or_scope)
         resource ||= resource_or_scope
         warden.set_user(resource, :scope => scope)
       end
@@ -103,16 +103,28 @@ def stored_location_for(resource_or_scope)
       #     users.root # creates user_root_path
       #   end
       #
-      # If none of these are defined, root_path is used.
+      #
+      # If none of these are defined, root_path is used. However, if this default
+      # is not enough, you can customize it, for example:
+      #
+      #   def after_sign_in_path_for(resource)
+      #     if resource.is_a?(User) && resource.can_publish?
+      #       redirect_to publisher_url
+      #     else
+      #       super
+      #     end
+      #   end
+      #
       def after_sign_in_path_for(resource_or_scope)
         scope = Devise::Mapping.find_scope!(resource_or_scope)
         home_path = :"#{scope}_root_path"
         respond_to?(home_path, true) ? send(home_path) : root_path
       end
 
-      # The default to be used after signing out. This is used by all Devise
-      # controllers and you can overwrite it in your ApplicationController to
-      # provide a custom hook for a custom resource.
+      # Method used by sessions controller to sign out an user. You can overwrite
+      # it in your ApplicationController to provide a custom hook for a custom
+      # scope. Notice that differently from +after_sign_in_path_for+ this method
+      # receives a symbol with the scope, and not the resource.
       #
       # By default is the root_path.
       def after_sign_out_path_for(resource_or_scope)
@@ -124,16 +136,19 @@ def after_sign_out_path_for(resource_or_scope)
       #
       # If just a symbol is given, consider that the user was already signed in
       # through other means and just perform the redirection.
-      def sign_in_and_redirect(*args)
-        sign_in(*args) unless args.size == 1 && args.first.is_a?(Symbol)
-        redirect_to stored_location_for(args.first) || after_sign_in_path_for(args.first)
+      def sign_in_and_redirect(resource_or_scope, resource=nil, skip=false)
+        scope      = Devise::Mapping.find_scope!(resource_or_scope)
+        resource ||= resource_or_scope
+        sign_in(scope, resource) unless skip
+        redirect_to stored_location_for(scope) || after_sign_in_path_for(resource)
       end
 
       # Sign out an user and tries to redirect to the url specified by
       # after_sign_out_path_for.
       def sign_out_and_redirect(resource_or_scope)
-        sign_out(resource_or_scope)
-        redirect_to after_sign_out_path_for(resource_or_scope)
+        scope = Devise::Mapping.find_scope!(resource_or_scope)
+        sign_out(scope)
+        redirect_to after_sign_out_path_for(scope)
       end
 
       # Define authentication filters and accessor helpers based on mappings.

test/controllers/helpers_test.rb

@@ -148,9 +148,10 @@ def setup
     @controller.sign_in_and_redirect(admin)
   end
 
-  test 'only redirect if just a symbol is given' do
+  test 'only redirect if skip is given' do
+    admin = Admin.new
     @controller.expects(:redirect_to).with(admin_root_path)
-    @controller.sign_in_and_redirect(:admin)
+    @controller.sign_in_and_redirect(:admin, admin, true)
   end
 
   test 'sign out and redirect uses the configured after sign out path' do