Doing a general QA and Docblock

analysis/Docblock.php

@@ -93,7 +93,7 @@ public static function tags($string) {
 	}
 
 	/**
-	 * Parses `@param` docblock tags to separate out the parameter type from the description.
+	 * Parses `param` docblock tags to separate out the parameter type from the description.
 	 *
 	 * @param array $params An array of `@param` tags, as parsed from the `tags()` method.
 	 * @return array Returns an array where each key is a parameter name, and each value is an

analysis/Inspector.php

@@ -224,6 +224,7 @@ function($str) { return preg_quote($str, '/'); },
 	 *        - `'ranges'`: Returns a two-dimensional array where each key is a method name,
 	 *         and each value is an array of line numbers which are contained in the method.
 	 * @param array $options
+	 * @return mixed array|null|object
 	 */
 	public static function methods($class, $format = null, array $options = array()) {
 		$defaults = array('methods' => array(), 'group' => true, 'self' => true);
@@ -281,6 +282,7 @@ public static function methods($class, $format = null, array $options = array())
 	 * @param array $options Set of options:
 	 *        -'self': If true (default), only returns properties defined in `$class`,
 	 *         excluding properties from inherited classes.
+	 * @return mixed object lithium\analysis\Inspector._items.map|null
 	 */
 	public static function properties($class, array $options = array()) {
 		$defaults = array('properties' => array(), 'self' => true);
@@ -523,7 +525,7 @@ protected static function _items($class, $method, $options) {
 	 * Helper method to determine if a class applies to a list of modifiers.
 	 *
 	 * @param string $inspector ReflectionClass instance.
-	 * @param string $list List of modifiers to test.
+	 * @param array|string $list List of modifiers to test.
 	 * @return boolean Test result.
 	 */
 	protected static function _modifiers($inspector, $list = array()) {

analysis/Parser.php

@@ -22,7 +22,7 @@ class Parser extends \lithium\core\StaticObject {
 	 * present in the string, only the first is returned.
 	 *
 	 * @param string $string String of PHP code to get the token name of, i.e. `'=>'` or `'static'`.
-	 * @param string $options
+	 * @param array $options
 	 * @return mixed
 	 */
 	public static function token($string, array $options = array()) {

analysis/logger/adapter/Cache.php

@@ -45,9 +45,7 @@ class Cache extends \lithium\core\Object {
 
 	/**
 	 * Class constructor
-	 *
 	 * @param array $config
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$defaults = array(

analysis/logger/adapter/File.php

@@ -49,7 +49,6 @@ class File extends \lithium\core\Object {
 	 *              - `'format'` _string_: A `String::insert()`-compatible string that specifies how
 	 *                the log message should be formatted. The default format is
 	 *                `"{:timestamp} {:message}\n"`.
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$defaults = array(

analysis/logger/adapter/FirePhp.php

@@ -175,7 +175,7 @@ protected function _write($message) {
 	/**
 	 * Generates a string representation of the type and message, suitable for FirePHP.
 	 *
-	 * @param string $priority Represents the message priority.
+	 * @param string $type Represents the message priority.
 	 * @param string $message Contains the actual message to store.
 	 * @return array Returns the encoded string representations of the priority and message, in the
 	 *               `'key'` and `'content'` keys, respectively.

analysis/logger/adapter/Growl.php

@@ -97,7 +97,6 @@ class Growl extends \lithium\core\Object {
 	 *                `Logger::write()`.
 	 *              - `'notification'` _array_: A list of message types you wish to register with
 	 *                Growl to be able to send. Defaults to `array('Errors', 'Messages')`.
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$name = basename(LITHIUM_APP_PATH);
@@ -109,15 +108,15 @@ public function __construct(array $config = array()) {
 			'protocol' => 'udp',
 			'title'    => Inflector::humanize($name),
 			'notifications' => array('Errors', 'Messages'),
-			'registered' => false,
+			'registered' => false
 		);
 		parent::__construct($config + $defaults);
 	}
 
 	/**
 	 * Writes `$message` to a new Growl notification.
 	 *
-	 * @param string $priority The `Logger`-based priority of the message. This value is mapped to
+	 * @param string $type The `Logger`-based priority of the message. This value is mapped to
 	 *               a Growl-specific priority value if possible.
 	 * @param string $message Message to be shown.
 	 * @param array $options Any options that are passed to the `notify()` method. See the

analysis/logger/adapter/Syslog.php

@@ -53,7 +53,6 @@ class Syslog extends \lithium\core\Object {
 	 *              - `'facility'` _integer_: A flag specifying the program to use to log the
 	 *                messages. See the `openlog()` documentation for more information. Defaults to
 	 *                `LOG_USER`.
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$defaults = array('identity' => false, 'options'  => LOG_ODELAY, 'facility' => LOG_USER);

console/Command.php

@@ -58,9 +58,7 @@ class Command extends \lithium\core\Object {
 
 	/**
 	 * Constructor.
-	 *
 	 * @param array $config
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$defaults = array('request' => null, 'response' => array(), 'classes' => $this->_classes);
@@ -178,10 +176,10 @@ public function error($error = null, $options = array('nl' => 1)) {
 	 * result is part of `$options['choices']`.
 	 *
 	 * @param string $prompt
-	 * @param string $options
-	 * @return string
+	 * @param array $options
+	 * @return string|boolean
 	 */
-	public function in($prompt = null, $options = array()) {
+	public function in($prompt = null, array $options = array()) {
 		$defaults = array('choices' => null, 'default' => null, 'quit' => 'q');
 		$options += $defaults;
 		$choices = null;

console/Response.php

@@ -49,7 +49,6 @@ class Response extends \lithium\core\Object {
 	 *              - request object lithium\console\Request
 	 *              - output stream
 	 *              _ error stream
-	 * @return void
 	 */
 	public function __construct($config = array()) {
 		$defaults = array('output' => null, 'error' => null);

console/command/Create.php

@@ -85,8 +85,7 @@ public function run($command = null) {
 	 * Execute the given sub-command for the current request.
 	 *
 	 * @param string $command The sub-command name. example: Model, Controller, Test
-	 * @param string $params
-	 * @return void
+	 * @return boolean
 	 */
 	protected function _execute($command) {
 		try {
@@ -220,8 +219,8 @@ protected function _instance($name, array $config = array()) {
 	/**
 	 * Save a template with the current params. Writes file to `Create::$path`.
 	 *
-	 * @param string $params
-	 * @return boolean
+	 * @param array $params
+	 * @return boolean|string
 	 */
 	protected function _save(array $params = array()) {
 		$defaults = array('namespace' => null, 'class' => null);

console/command/Help.php

@@ -309,8 +309,8 @@ protected function _renderDescription($info) {
 	 * Add left padding for prettier display.
 	 *
 	 * @param string $message the text to render.
-	 * @param string $level the level of indentation.
-	 * @return void
+	 * @param integer|string $level the level of indentation.
+	 * @return string
 	 */
 	protected function _pad($message, $level = 1) {
 		$padding = str_repeat(' ', $level * 4);

console/command/Library.php

@@ -135,8 +135,9 @@ protected function _init() {
 	 *
 	 * @param string $key (server)
 	 * @param string $value value of key
-	 * @param string $options [optional]
-	 * @return void
+	 * @param boolean|string $options [optional]
+	 * @return bool|int|array array _settings when $key and $value aren't set and
+	 *         int bytes written when content is written or bool false on failure
 	 */
 	public function config($key = null, $value = null, $options = true) {
 		if (empty($key) || empty($value)) {
@@ -520,8 +521,7 @@ public function push($name = null) {
 	/**
 	 * Update installed plugins. For plugins, runs update commands specified in Formula.
 	 *
-	 * @param string $name
-	 * @return boolean
+	 * @todo implement
 	 */
 	public function update() {
 		$this->error('Please implement me');

console/command/create/Mock.php

@@ -19,13 +19,13 @@
  */
 class Mock extends \lithium\console\command\Create {
 
-    /**
-     * Get the namespace for the mock.
-     *
-     * @param string $request
-     * @param string $options
-     * @return string
-     */
+	/**
+	 * Get the namespace for the mock.
+	 *
+	 * @param string $request
+	 * @param array|string $options
+	 * @return string
+	 */
 	protected function _namespace($request, $options = array()) {
 		$request->params['command'] = $request->action;
 		return parent::_namespace($request, array('prepend' => 'tests.mocks.'));

console/command/create/View.php

@@ -24,6 +24,7 @@ class View extends \lithium\console\command\Create {
      * Override the save method to handle view specific params.
      *
      * @param array $params
+     * @return mixed
      */
 	protected function _save(array $params = array()) {
 		$params['path'] = Inflector::underscore($this->request->action);

console/command/g11n/Extract.php

@@ -59,8 +59,7 @@ public function run() {
 	/**
 	 * Extracts translatable strings from multiple files.
 	 *
-	 * @param array $files Absolute paths to files.
-	 * @return array
+	 * @return array|boolean
 	 */
 	protected function _extract() {
 		$message[] = 'A `Catalog` class configuration with an adapter that is capable of';

core/Adaptable.php

@@ -207,6 +207,7 @@ public static function enabled($name) {
 	 * @param string $class The fully-namespaced class name of the adapter to instantiate.
 	 * @param array $config The configuration array to be passed to the adapter instance. See the
 	 *              `$config` parameter of `Object::__construct()`.
+	 * @return lithium\core\Adaptable._filter|adapter class
 	 * @filter This method can be filtered.
 	 */
 	protected static function _initAdapter($class, array $config) {

core/Object.php

@@ -84,7 +84,6 @@ class Object {
 	 *              - `'init'` _boolean_: Controls constructor behavior for calling the `_init()`
 	 *                method. If `false`, the method is not called, otherwise it is. Defaults to
 	 *                `true`.
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$defaults = array('init' => true);

data/Collection.php

@@ -98,9 +98,7 @@ abstract class Collection extends \lithium\util\Collection {
 
 	/**
 	 * Class constructor
-	 *
 	 * @param array $config
-	 * @return void
 	 */
 	public function __construct(array $config = array()) {
 		$defaults = array('data' => array(), 'model' => null);

data/Model.php

@@ -269,7 +269,7 @@ class Model extends \lithium\core\StaticObject {
 		'order'      => null,
 		'limit'      => null,
 		'page'       => null,
-		'with'       => array(),
+		'with'       => array()
 	);
 
 	/**
@@ -298,7 +298,6 @@ class Model extends \lithium\core\StaticObject {
 	 * Sets default connection options and connects default finders.
 	 *
 	 * @param array $options
-	 * @return void
 	 * @todo Merge in inherited config from AppModel and other parent classes.
 	 */
 	public static function __init() {
@@ -415,15 +414,15 @@ public static function __callStatic($method, $params) {
 	 *
 	 * @param string $type The find type, which is looked up in `Model::$_finders`. By default it
 	 *        accepts `all`, `first`, `list` and `count`,
-	 * @param string $options Options for the query. By default, accepts:
+	 * @param array $options Options for the query. By default, accepts:
 	 *        - `conditions`: The conditional query elements, e.g.
 	 *                 `'conditions' => array('published' => true)`
 	 *        - `fields`: The fields that should be retrieved. When set to `null`, defaults to
 	 *             all fields.
 	 *        - `order`: The order in which the data will be returned, e.g. `'order' => 'ASC'`.
 	 *        - `limit`: The maximum number of records to return.
 	 *        - `page`: For pagination of data.
-	 * @return void
+	 * @return mixed
 	 * @filter This method can be filtered.
 	 */
 	public static function find($type, array $options = array()) {
@@ -1084,6 +1083,7 @@ protected static function _findFilters() {
 	/**
 	 * @deprecated
 	 * @see lithium\data\Model::connection()
+	 * @return connection object
 	 */
 	protected static function &_connection() {
 		return static::connection();

data/Source.php

@@ -142,7 +142,7 @@ abstract public function disconnect();
 	 * Returns a list of objects (sources) that models can bind to, i.e. a list of tables in the
 	 * case of a database, or REST collections, in the case of a web service.
 	 *
-	 * @param string $model The fully-name-spaced class name of the object making the request.
+	 * @param string $class The fully-name-spaced class name of the object making the request.
 	 * @return array Returns an array of objects to which models can connect.
 	 */
 	abstract public function sources($class = null);
@@ -163,7 +163,10 @@ abstract public function describe($entity, array $meta = array());
 
 	/**
 	 * Defines or modifies the default settings of a relationship between two models.
-	 *
+	 * @param $class the primary model of the relationship
+	 * @param $type the type of the relationship (hasMany, hasOne, belongsTo)
+	 * @param $name the name of the relationship
+	 * @param array $options relationship options
 	 * @return array Returns an array containing the configuration for a model relationship.
 	 */
 	abstract public function relationship($class, $type, $name, array $options = array());

data/collection/RecordSet.php

@@ -151,7 +151,7 @@ public function rewind() {
 	/**
 	 * Returns the currently pointed to record in the set.
 	 *
-	 * @return `Record`
+	 * @return object `Record`
 	 */
 	public function current() {
 		return $this->_data[$this->_pointer];
@@ -230,7 +230,8 @@ public function to($format, array $options = array()) {
 				if (!(is_scalar(current($this->_index)) && $options['indexed'])) {
 					break;
 				}
-				$result = ($this->_index && $result) ? array_combine($this->_index, $result) : array();
+				$indexAndResult = ($this->_index && $result);
+				$result =  $indexAndResult ? array_combine($this->_index, $result) : array();
 			break;
 			default:
 				$result = parent::to($format, $options);
@@ -288,7 +289,7 @@ protected function _populate($data = null, $key = null) {
 		$record = is_object($data) ? $data : $this->_mapRecord($data);
 		$key = $model::key($record);
 
-		if(!$key) {
+		if (!$key) {
 			$key = count($this->_data);
 		}
 

data/entity/Document.php

@@ -340,7 +340,6 @@ public function offsetSet($offset, $value) {
 	 *
 	 * @param mixed $offset String or integer indicating the offset or the name of a field in an
 	 *              individual document.
-	 * @param mixed $value The value to assign to the field.
 	 * @return boolean Returns `true` if `$offset` is a field in the document, otherwise `false`.
 	 */
 	public function offsetExists($offset) {
@@ -433,8 +432,8 @@ public function next() {
 	 * non-numeric.
 	 *
 	 * @param string $field The name of the field to be incrememnted.
-	 * @param string $value The value to increment the field by. Defaults to `1` if this parameter
-	 *               is not specified.
+	 * @param integer|string $value The value to increment the field by. Defaults to `1` if this
+	 *               parameter is not specified.
 	 * @return integer Returns the current value of `$field`, based on the value retrieved from the
 	 *         data source when the entity was loaded, plus any increments applied. Note that it
 	 *         may not reflect the most current value in the persistent backend data source.
@@ -454,4 +453,4 @@ public function increment($field, $value = 1) {
 	}
 }
 
-?>
+?>