Index: includes/session.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/session.inc,v
retrieving revision 1.48
diff -u -p -r1.48 session.inc
--- includes/session.inc	16 Apr 2008 11:35:51 -0000	1.48
+++ includes/session.inc	6 May 2008 14:03:23 -0000
@@ -4,17 +4,64 @@
 /**
  * @file
  * User session handling functions.
+ *
+ * The session save handlers:
+ * - _sess_open()
+ * - _sess_close()
+ * - _sess_read()
+ * - _sess_write()
+ * are assigned by session_set_save_handler() and should not be called directly. 
+ * Instead, access session variables via the $_SESSION superglobal.
  */
 
-function sess_open($save_path, $session_name) {
+/**
+ * Session handler assigned by session_set_save_handler().
+ * 
+ * This function is used to set the save path for the current session. Because 
+ * Drupal stores session data in the database, this function does not need to set anything.
+ *
+ * This function should not be used directly. Session variables should instead be 
+ * accessed via the $_SESSION superglobal.
+ *
+ * @return
+ *   This function will always return TRUE.
+*/    
+function _sess_open() {
   return TRUE;
 }
 
-function sess_close() {
+/**
+ * Session handler assigned by session_set_save_handler().
+ * 
+ * This function is used to close the current session. Because 
+ * Drupal stores session data in the database immediately on write, this function does 
+ * not need to do anything.
+ *
+ * This function should not be used directly. Session variables should instead be 
+ * accessed via the $_SESSION superglobal.
+ *
+ * @return
+ *   This function will always return TRUE.
+*/    
+function _sess_close() {
   return TRUE;
 }
 
-function sess_read($key) {
+/**
+ * Session handler assigned by session_set_save_handler().
+ * 
+ * This function retrieves the current session from the database and also loads 
+ * the current user's roles into the user object.
+ *
+ * This function should not be used directly. Session variables should instead be 
+ * accessed via the $_SESSION superglobal.
+ *
+ * @param $key
+ *   Session ID
+ * @return
+ *   Either an array of the session data, or an empty string, if no data was found or the user is anonymous.
+*/
+function _sess_read($key) {
   global $user;
 
   // Write and Close handlers are called after destructing objects since PHP 5.0.5
@@ -53,7 +100,22 @@ function sess_read($key) {
   return $user->session;
 }
 
-function sess_write($key, $value) {
+/**
+ * Session handler assigned by session_set_save_handler().
+ * 
+ * This function writes the current session to the database.
+ *
+ * This function should not be used directly. Session variables should instead be 
+ * accessed via the $_SESSION superglobal.
+ *
+ * @param $key
+ *   Session ID
+ * @param $value
+ *   Serialized array of the session data.
+ * @return
+ *   This function will always return TRUE.
+*/
+function _sess_write($key, $value) {
   global $user;
 
   // If saving of session data is disabled or if the client doesn't have a session,