[ci skip] feature/session (#3073): Add missing method docblocks

6 files changed, 267 insertions, 0 deletions

diff --git a/system/libraries/Session/Session.php b/system/libraries/Session/Session.php
index 4a96aa6b1..5c61002a6 100644
--- a/system/libraries/Session/Session.php
+++ b/system/libraries/Session/Session.php
@@ -179,6 +179,16 @@ class CI_Session {
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * CI Load Classes
+	 *
+	 * An internal method to load all possible dependency and extension
+	 * classes. It kind of emulates the CI_Driver library, but is
+	 * self-sufficient.
+	 *
+	 * @param	string	$driver	Driver name
+	 * @return	string	Driver class name
+	 */
 	protected function _ci_load_classes($driver)
 	{
 		// PHP 5.4 compatibility
diff --git a/system/libraries/Session/Session_driver.php b/system/libraries/Session/Session_driver.php
index de1908ac6..c4fbde4f8 100644
--- a/system/libraries/Session/Session_driver.php
+++ b/system/libraries/Session/Session_driver.php
@@ -89,6 +89,14 @@ abstract class CI_Session_driver implements SessionHandlerInterface {
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Cookie destroy
+	 *
+	 * Internal method to force removal of a cookie by the client
+	 * when session_destroy() is called.
+	 *
+	 * @return	bool
+	 */
 	protected function _cookie_destroy()
 	{
 		return setcookie(
diff --git a/system/libraries/Session/drivers/Session_database_driver.php b/system/libraries/Session/drivers/Session_database_driver.php
index 055a1a613..87d80a2b0 100644
--- a/system/libraries/Session/drivers/Session_database_driver.php
+++ b/system/libraries/Session/drivers/Session_database_driver.php
@@ -110,6 +110,15 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Open
+	 *
+	 * Initializes the database connection
+	 *
+	 * @param	string	$save_path	Table name
+	 * @param	string	$name		Session cookie name, unused
+	 * @return	bool
+	 */
 	public function open($save_path, $name)
 	{
 		return empty($this->_db->conn_id)
@@ -119,6 +128,14 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Read
+	 *
+	 * Reads session data and acquires a lock
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	string	Serialized session data
+	 */
 	public function read($session_id)
 	{
 		if ($this->_get_lock($session_id) !== FALSE)
@@ -158,6 +175,17 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 		return '';
 	}
 
+	// ------------------------------------------------------------------------
+
+	/**
+	 * Write
+	 *
+	 * Writes (create / update) session data
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @param	string	$session_data	Serialized session data
+	 * @return	bool
+	 */
 	public function write($session_id, $session_data)
 	{
 		// Was the ID regenerated?
@@ -219,6 +247,13 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Close
+	 *
+	 * Releases locks
+	 *
+	 * @return	void
+	 */
 	public function close()
 	{
 		return ($this->_lock)
@@ -228,6 +263,14 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Destroy
+	 *
+	 * Destroys the current session.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	public function destroy($session_id)
 	{
 		if ($this->_lock)
@@ -248,6 +291,14 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Garbage Collector
+	 *
+	 * Deletes expired sessions
+	 *
+	 * @param	int 	$maxlifetime	Maximum lifetime of sessions
+	 * @return	bool
+	 */
 	public function gc($maxlifetime)
 	{
 		return $this->_db->delete($this->_config['save_path'], 'timestamp < '.(time() - $maxlifetime));
@@ -255,6 +306,14 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Get lock
+	 *
+	 * Acquires a lock, depending on the underlying platform.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	protected function _get_lock($session_id)
 	{
 		if ($this->_platform === 'mysql')
@@ -285,6 +344,13 @@ class CI_Session_database_driver extends CI_Session_driver implements SessionHan
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Release lock
+	 *
+	 * Releases a previously acquired lock
+	 *
+	 * @return	bool
+	 */
 	protected function _release_lock()
 	{
 		if ( ! $this->_lock)
diff --git a/system/libraries/Session/drivers/Session_files_driver.php b/system/libraries/Session/drivers/Session_files_driver.php
index 761eed46f..95ab7f14c 100644
--- a/system/libraries/Session/drivers/Session_files_driver.php
+++ b/system/libraries/Session/drivers/Session_files_driver.php
@@ -101,6 +101,15 @@ class CI_Session_files_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Open
+	 *
+	 * Sanitizes the save_path directory.
+	 *
+	 * @param	string	$save_path	Path to session files' directory
+	 * @param	string	$name		Session cookie name, unused
+	 * @return	bool
+	 */
 	public function open($save_path, $name)
 	{
 		if ( ! is_dir($save_path) && ! mkdir($save_path, 0700, TRUE))
@@ -119,6 +128,14 @@ class CI_Session_files_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Read
+	 *
+	 * Reads session data and acquires a lock
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	string	Serialized session data
+	 */
 	public function read($session_id)
 	{
 		// This might seem weird, but PHP 5.6 introduces session_reset(),
@@ -180,6 +197,17 @@ class CI_Session_files_driver extends CI_Session_driver implements SessionHandle
 		return $session_data;
 	}
 
+	// ------------------------------------------------------------------------
+
+	/**
+	 * Write
+	 *
+	 * Writes (create / update) session data
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @param	string	$session_data	Serialized session data
+	 * @return	bool
+	 */
 	public function write($session_id, $session_data)
 	{
 		// If the two IDs don't match, we have a session_regenerate_id() call
@@ -230,6 +258,13 @@ class CI_Session_files_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Close
+	 *
+	 * Releases locks and closes file descriptor.
+	 *
+	 * @return	void
+	 */
 	public function close()
 	{
 		if (is_resource($this->_file_handle))
@@ -246,6 +281,14 @@ class CI_Session_files_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Destroy
+	 *
+	 * Destroys the current session.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	public function destroy($session_id)
 	{
 		if ($this->close())
@@ -265,6 +308,14 @@ class CI_Session_files_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Garbage Collector
+	 *
+	 * Deletes expired sessions
+	 *
+	 * @param	int 	$maxlifetime	Maximum lifetime of sessions
+	 * @return	bool
+	 */
 	public function gc($maxlifetime)
 	{
 		if ( ! is_dir($this->_config['save_path']) OR ($files = scandir($this->_config['save_path'])) === FALSE)
diff --git a/system/libraries/Session/drivers/Session_memcached_driver.php b/system/libraries/Session/drivers/Session_memcached_driver.php
index e2b568f52..683bb5c69 100644
--- a/system/libraries/Session/drivers/Session_memcached_driver.php
+++ b/system/libraries/Session/drivers/Session_memcached_driver.php
@@ -94,6 +94,15 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Open
+	 *
+	 * Sanitizes save_path and initializes connections.
+	 *
+	 * @param	string	$save_path	Server path(s)
+	 * @param	string	$name		Session cookie name, unused
+	 * @return	bool
+	 */
 	public function open($save_path, $name)
 	{
 		$this->_memcached = new Memcached();
@@ -141,6 +150,14 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Read
+	 *
+	 * Reads session data and acquires a lock
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	string	Serialized session data
+	 */
 	public function read($session_id)
 	{
 		if (isset($this->_memcached) && $this->_get_lock($session_id))
@@ -156,6 +173,17 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 		return FALSE;
 	}
 
+	// ------------------------------------------------------------------------
+
+	/**
+	 * Write
+	 *
+	 * Writes (create / update) session data
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @param	string	$session_data	Serialized session data
+	 * @return	bool
+	 */
 	public function write($session_id, $session_data)
 	{
 		if ( ! isset($this->_memcached))
@@ -196,6 +224,13 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Close
+	 *
+	 * Releases locks and closes connection.
+	 *
+	 * @return	void
+	 */
 	public function close()
 	{
 		if (isset($this->_memcached))
@@ -215,6 +250,14 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Destroy
+	 *
+	 * Destroys the current session.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	public function destroy($session_id)
 	{
 		if (isset($this->_memcached, $this->_lock_key))
@@ -228,6 +271,14 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Garbage Collector
+	 *
+	 * Deletes expired sessions
+	 *
+	 * @param	int 	$maxlifetime	Maximum lifetime of sessions
+	 * @return	bool
+	 */
 	public function gc($maxlifetime)
 	{
 		// Not necessary, Memcached takes care of that.
@@ -236,6 +287,14 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Get lock
+	 *
+	 * Acquires an (emulated) lock.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	protected function _get_lock($session_id)
 	{
 		if (isset($this->_lock_key))
@@ -289,6 +348,13 @@ class CI_Session_memcached_driver extends CI_Session_driver implements SessionHa
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Release lock
+	 *
+	 * Releases a previously acquired lock
+	 *
+	 * @return	bool
+	 */
 	protected function _release_lock()
 	{
 		if (isset($this->_memcached, $this->_lock_key) && $this->_lock)
diff --git a/system/libraries/Session/drivers/Session_redis_driver.php b/system/libraries/Session/drivers/Session_redis_driver.php
index cde587b97..a0ec40907 100644
--- a/system/libraries/Session/drivers/Session_redis_driver.php
+++ b/system/libraries/Session/drivers/Session_redis_driver.php
@@ -111,6 +111,15 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Open
+	 *
+	 * Sanitizes save_path and initializes connection.
+	 *
+	 * @param	string	$save_path	Server path
+	 * @param	string	$name		Session cookie name, unused
+	 * @return	bool
+	 */
 	public function open($save_path, $name)
 	{
 		if (empty($this->_config['save_path']))
@@ -142,6 +151,14 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Read
+	 *
+	 * Reads session data and acquires a lock
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	string	Serialized session data
+	 */
 	public function read($session_id)
 	{
 		if (isset($this->_redis) && $this->_get_lock($session_id))
@@ -157,6 +174,17 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 		return FALSE;
 	}
 
+	// ------------------------------------------------------------------------
+
+	/**
+	 * Write
+	 *
+	 * Writes (create / update) session data
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @param	string	$session_data	Serialized session data
+	 * @return	bool
+	 */
 	public function write($session_id, $session_data)
 	{
 		if ( ! isset($this->_redis))
@@ -197,6 +225,13 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Close
+	 *
+	 * Releases locks and closes connection.
+	 *
+	 * @return	void
+	 */
 	public function close()
 	{
 		if (isset($this->_redis))
@@ -225,6 +260,14 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Destroy
+	 *
+	 * Destroys the current session.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	public function destroy($session_id)
 	{
 		if (isset($this->_redis, $this->_lock_key))
@@ -242,6 +285,14 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Garbage Collector
+	 *
+	 * Deletes expired sessions
+	 *
+	 * @param	int 	$maxlifetime	Maximum lifetime of sessions
+	 * @return	bool
+	 */
 	public function gc($maxlifetime)
 	{
 		// Not necessary, Redis takes care of that.
@@ -250,6 +301,14 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Get lock
+	 *
+	 * Acquires an (emulated) lock.
+	 *
+	 * @param	string	$session_id	Session ID
+	 * @return	bool
+	 */
 	protected function _get_lock($session_id)
 	{
 		if (isset($this->_lock_key))
@@ -309,6 +368,13 @@ class CI_Session_redis_driver extends CI_Session_driver implements SessionHandle
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * Release lock
+	 *
+	 * Releases a previously acquired lock
+	 *
+	 * @return	bool
+	 */
 	protected function _release_lock()
 	{
 		if (isset($this->_redis, $this->_lock_key) && $this->_lock)