auth.rb in ramaze-2011.01

- old
+ new

@@ -6,10 +6,17 @@
 
     # A simple way to do authentication without a model.
     # Please have a look at the docs of Auth#auth_login.
     #
     # If you want to do authentication with a model see Helper::User instead.
+    
+    ##
+    # The Auth helper can be used for authentication without using a model.
+    # This can be useful when working with very basic applications that don't require database access.
+    #
+    # If you're looking for a way to do authentication using a model you should take a look at Helper::User instead.
+    #
     module Auth
       Helper::LOOKUP << self
       include Ramaze::Traited
 
       trait :auth_table => {}
@@ -17,35 +24,56 @@
       trait :auth_post_only => false
 
       def self.included(into)
         into.helper(:stack)
       end
-
+      
+      ##
+      # Log a user in based on the :username and :password key in the request hash.
+      #
+      # @return [String] The login template in case the user's login data was incorrect.
+      #
       def login
         return auth_template if trait[:auth_post_only] and !request.post?
         @username, password = request[:username, :password]
         answer(request.referer) if auth_login(@username, password)
         return auth_template
       end
 
+      ##
+      # Log the user out and redirect him back to the previous page.
+      #
       def logout
         auth_logout
         answer(request.referer)
       end
 
       private
 
+      ##
+      # Validate the user's session and redirect him/her to the login page in case the user isn't logged in.
+      #
       def login_required
         call(r(:login)) unless logged_in?
       end
 
-      # @return [true false] whether user is logged in right now
+      ##
+      # Validate the user's session and return a boolean that indicates if the user is logged in or not.
+      #
+      # @return [true false] Whether user is logged in right now
+      #
       def logged_in?
         !!session[:logged_in]
       end
 
-      # @return
+      ##
+      # Try to log the user in based on the username and password.
+      # This method is called by the login() method and shouldn't be called directly.
+      #
+      # @param [String] user The users's username.
+      # @param [String] pass The user's password.
+      #
       def auth_login(user, pass)
         return unless user and pass
         return if user.empty? or pass.empty?
         return unless table = ancestral_trait[:auth_table]
         return unless hashify = ancestral_trait[:auth_hashify]
@@ -60,15 +88,21 @@
 
         session[:logged_in] = true
         session[:username] = user
       end
 
+      ##
+      # Remove the session items that specified that the user was logged in.
+      #
       def auth_logout
         session.delete(:logged_in)
         session.delete(:username)
       end
 
-      # @return [String] template for auth
+      ##
+      # Method that returns a small form that can be used for logging in.
+      #
+      # @return [String] The login form.
       def auth_template
         <<-TEMPLATE.strip!
 <form method="post" action="#{r(:login)}">
   <ul style="list-style:none;">
     <li>Username: <input type="text" name="username" value="#@username"/></li>