From 4ba34290c7973c7aed5eb25d5912b312b05cade4 Mon Sep 17 00:00:00 2001
From: Carlos Antonio da Silva <carlosantoniodasilva@gmail.com>
Date: Sun, 22 Nov 2009 23:29:03 -0200
Subject: [PATCH] Improving docs about timeoutable

---
 lib/devise/hooks/timeoutable.rb  | 11 ++++++++---
 lib/devise/models/timeoutable.rb |  9 ++++++++-
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/lib/devise/hooks/timeoutable.rb b/lib/devise/hooks/timeoutable.rb
index af0d92cb..bb906c59 100644
--- a/lib/devise/hooks/timeoutable.rb
+++ b/lib/devise/hooks/timeoutable.rb
@@ -1,10 +1,15 @@
+# Each time a record is set we check whether it's session has already timed out
+# or not, based on last request time. If so, the record is logged out and
+# redirected to the sign in page. Also, each time the request comes and the
+# record is set, we set the last request time inside it's scoped session to
+# verify timeout in the following request.
 Warden::Manager.after_set_user do |record, warden, options|
-  if record.present?
+  if record.present? && record.respond_to?(:timeout?)
     scope = options[:scope]
     # Current record may have already be logged out by another hook.
     # For instance, Devise confirmable hook may have logged the record out.
-    # TODO: move this verify to warden: he should stop the hooks if the record
-    # is logged out by any of them.
+    # TODO: is it possible to move this check to warden?
+    # It should stop the hooks if the record is logged out by any of them.
     if warden.authenticated?(scope)
       last_request_at = warden.session(scope)['last_request_at']
       if record.timeout?(last_request_at)
diff --git a/lib/devise/models/timeoutable.rb b/lib/devise/models/timeoutable.rb
index 79c1ca3b..fe134881 100644
--- a/lib/devise/models/timeoutable.rb
+++ b/lib/devise/models/timeoutable.rb
@@ -3,7 +3,14 @@ require 'devise/hooks/timeoutable'
 module Devise
   module Models
 
-    # Timeoutable
+    # Timeoutable takes care of veryfing whether a user session has already
+    # expired or not. When a session expires after the configured time, the user
+    # will be asked for credentials again, it means, he/she will be redirected
+    # to the sign in page.
+    #
+    # Configuration:
+    #
+    #   timeout: the time you want to timeout the user session without activity.
     module Timeoutable
 
       def self.included(base)