Updated phpdoc for ChamiloSession class

main/inc/lib/chamilo_session.class.php

@@ -1,7 +1,6 @@
 <?php
-
 /**
- * Chamilo session.
+ * Chamilo session (i.e. the session that maintains the connection open after usr login)
  * 
  * Usage:
  * 
@@ -18,13 +17,16 @@
  * @license see /license.txt
  * @author Laurent Opprecht <laurent@opprecht.info> for the Univesity of Geneva
  */
+/**
+ * ChamiloSession class definition
+ */
 class ChamiloSession extends System\Session
 {
 
     const NAME = 'ch_sid';
 
     /**
-     *
+     * Generate new session instance
      * @return ChamiloSession 
      */
     static function instance()
@@ -36,12 +38,21 @@ class ChamiloSession extends System\Session
         return $result;
     }
 
+    /**
+     * Returns the session lifetime
+     * @return int The session lifetime as defined in the config file, in seconds
+     */
     static function session_lifetime()
     {
         global $_configuration;
         return $_configuration['session_lifetime'];
     }
 
+    /**
+     * Returns whether the sessions are stored in the database (or not)
+     * @return bool True if session data are stored in the database, false if they're stored on disk
+     * @assert (null) === false
+     */
     static function session_stored_in_db()
     {
         return self::read('session_stored_in_db', false);
@@ -57,6 +68,7 @@ class ChamiloSession extends System\Session
      *
      * @author Olivier Brouckaert
      * @param  string variable - the variable name to save into the session
+     * @return void
      */
     static function start($already_installed = true)
     {
@@ -96,7 +108,8 @@ class ChamiloSession extends System\Session
         //Use entropy file    
         //session.entropy_file
         //ini_set('session.entropy_length', 128);
-        //Do not include the identifier in the URL, and not to read the URL for identifiers.
+        //Do not include the identifier in the URL, and not to read the URL for
+        // identifiers.
         ini_set('session.use_trans_sid', 0);
 
         session_name(self::NAME);
@@ -118,8 +131,7 @@ class ChamiloSession extends System\Session
     }
 
     /**
-     * Session start time: that is the last time the user accesseed the application.
-     * 
+     * Session start time: that is the last time the user loaded a page (before this time)
      * @return int timestamp
      */
     function start_time()
@@ -128,9 +140,9 @@ class ChamiloSession extends System\Session
     }
 
     /**
-     * Session end time: when the session expires.
-     * 
-     * @return int timestamp
+     * Session end time: when the session expires. This is made of the last page
+     * load time + a number of seconds
+     * @return int UNIX timestamp (server's timezone)
      */
     function end_time()
     {
@@ -142,8 +154,7 @@ class ChamiloSession extends System\Session
     /**
      * Returns true if the session is stalled. I.e. if session end time is
      * greater than now. Returns false otherwise.
-     * 
-     * @return bool
+     * @return bool True if the session is expired. False otherwise
      */
     function is_stalled()
     {
@@ -151,8 +162,8 @@ class ChamiloSession extends System\Session
     }
 
     /**
-     * Returns true if the session is valid - if it is not stalled - false otherwise.
-     * @return bool
+     * Returns whether the session is not stalled
+     * @return bool True if the session is still valid, false otherwise
      */
     public function is_valid()
     {
@@ -161,8 +172,7 @@ class ChamiloSession extends System\Session
 
     /**
      * The current (logged in) user.
-     * 
-     * @return CurrentUser
+     * @return CurrentUser The current user instance
      */
     public function user()
     {
@@ -172,10 +182,10 @@ class ChamiloSession extends System\Session
         }
         return $result;
     }
-    
+
     /**
-     *
-     * @return CurrentCourse
+     * Returns the current (active) course
+     * @return CurrentCourse The current course instance
      */
     public function course()
     {
@@ -185,17 +195,13 @@ class ChamiloSession extends System\Session
         }
         return $result;
     }
-    
-   
 
     /**
      * The current group for the current (logged in) user.
-     * 
-     * @return int
+     * @return int the current group id
      */
     public function group_id()
     {
         return Session::read('_gid');
     }
-
 }