Permalink
Browse files

Cleaning up docblocks in `\storage\Session`.

  • Loading branch information...
1 parent a6d4e93 commit c571ed74fd1ce1b06dfc65161b8f829547d77285 @nateabele nateabele committed Jun 11, 2011
Showing with 43 additions and 25 deletions.
  1. +43 −25 storage/Session.php
View
@@ -21,8 +21,8 @@
* In most cases, you will configure various named session configurations in your bootstrap
* process, which will then be available to you in all other parts of your application.
*
- * Each adapter provides a consistent interface for the basic cache operations of `write`, `read`
- * and `delete`, which can be used interchangeably between all adapters.
+ * Each adapter provides a consistent interface for the basic session operations like `read`,
+ * `write`, `delete` and `check`, which can be used interchangeably between all adapters.
*
* For more information on `Session` methods and specific adapters, please see their relevant
* documentation.
@@ -33,31 +33,33 @@
class Session extends \lithium\core\Adaptable {
/**
- * Stores configurations for cache adapters
+ * Stores configurations arrays for session adapters, keyed by configuration name.
*
- * @var object Collection of cache configurations
+ * @var array
*/
protected static $_configurations = array();
/**
- * Libraries::locate() compatible path to adapters for this class.
+ * A dot-separated path for use by `Libraries::locate()`. Used to look up the correct type of
+ * adapters for this class.
*
- * @var string Dot-delimited path.
+ * @var string
*/
protected static $_adapters = 'adapter.storage.session';
/**
- * Libraries::locate() compatible path to strategies for this class.
+ * `Libraries::locate()` compatible path to strategies for this class.
*
- * @var string Dot-delimited path.
+ * @var string
*/
protected static $_strategies = 'strategy.storage.session';
/**
- * Returns key used to identify the session.
+ * Returns the key used to identify the session.
*
- * @param mixed $name Named session configuration.
- * @return null|string Value of key, or `null` if no named configuration exists.
+ * @param mixed $name Optional named session configuration.
+ * @return string Returns the value of the session identifier key, or `null` if no named
+ * configuration exists, or no session has been started.
*/
public static function key($name = null) {
return is_object($adapter = static::adapter($name)) ? $adapter->key() : null;
@@ -67,8 +69,8 @@ public static function key($name = null) {
* Indicates whether the the current request includes information on a previously started
* session.
*
- * @param string $name Named session configuration.
- * @return boolean Returns true if a the request includes a key from a previously created
+ * @param string $name Optional named session configuration.
+ * @return boolean Returns `true` if a the request includes a key from a previously created
* session.
*/
public static function isStarted($name = null) {
@@ -78,9 +80,13 @@ public static function isStarted($name = null) {
/**
* Reads a value from a persistent session store.
*
- * @param string $key Key to be read
- * @param array $options Optional parameters that this method accepts.
- * @return mixed Read result on successful session read, null otherwise.
+ * @param string $key Key to be read.
+ * @param array $options Optional parameters that this method accepts:
+ * - `'name'` _string_: To force the read from a specific adapter, specify the name
+ * of the configuration (i.e. `'default'`) here.
+ * - `'strategies'` _boolean_: Indicates whether or not a configuration's applied
+ * strategy classes should be enabled for this operation. Defaults to `true`.
+ * @return mixed Read result on successful session read, `null` otherwise.
* @filter This method may be filtered.
*/
public static function read($key = null, array $options = array()) {
@@ -112,10 +118,14 @@ public static function read($key = null, array $options = array()) {
/**
* Writes a persistent value to one or more session stores.
*
- * @param string $key Key to be read
- * @param mixed $value Data to be stored
- * @param array $options Optional parameters that this method accepts.
- * @return boolean True on successful write, false otherwise.
+ * @param string $key Key to be written.
+ * @param mixed $value Data to be stored.
+ * @param array $options Optional parameters that this method accepts:
+ * - `'name'` _string_: To force the write to a specific adapter, specify the name
+ * of the configuration (i.e. `'default'`) here.
+ * - `'strategies'` _boolean_: Indicates whether or not a configuration's applied
+ * strategy classes should be enabled for this operation. Defaults to `true`.
+ * @return boolean Returns `true` on successful write, `false` otherwise.
* @filter This method may be filtered.
*/
public static function write($key, $value = null, array $options = array()) {
@@ -157,8 +167,12 @@ public static function write($key, $value = null, array $options = array()) {
* session adapters.
*
* @param string $key The name of the session key to delete.
- * @param array $options Optional parameters that this method accepts.
- * @return void
+ * @param array $options Optional parameters that this method accepts:
+ * - `'name'` _string_: To force the delete to a specific adapter, specify the name
+ * of the configuration (i.e. `'default'`) here.
+ * - `'strategies'` _boolean_: Indicates whether or not a configuration's applied
+ * strategy classes should be enabled for this operation. Defaults to `true`.
+ * @return boolean Returns `true` on sucessful delete, or `false` on failure.
* @filter This method may be filtered.
*/
public static function delete($key, array $options = array()) {
@@ -197,7 +211,11 @@ public static function delete($key, array $options = array()) {
* Clears all keys from a single adapter (if a `'name'` options is specified) or all
* session adapters.
*
- * @param array $options Optional parameters that this method accepts.
+ * @param array $options Optional parameters that this method accepts:
+ * - `'name'` _string_: To force the write to a specific adapter, specify the name
+ * of the configuration (i.e. `'default'`) here.
+ * - `'strategies'` _boolean_: Indicates whether or not a configuration's applied
+ * strategy classes should be enabled for this operation. Defaults to `true`.
* @filter
*/
public static function clear(array $options = array()) {
@@ -270,12 +288,12 @@ public static function check($key, array $options = array()) {
/**
* Returns the adapter object instance of the named configuration.
*
- * @param null|string $name Named configuration. If not set, the last configured
+ * @param string $name Named configuration. If not set, the last configured
* adapter object instance will be returned.
* @return object Adapter instance.
*/
public static function adapter($name = null) {
- if (empty($name)) {
+ if (!$name) {
if (!$names = array_keys(static::$_configurations)) {
return;
}

0 comments on commit c571ed7

Please sign in to comment.