Add false as return value of field()

+ improve DocBlocks

lib/Cake/Model/Datasource/DboSource.php

@@ -739,9 +739,9 @@ public function fetchVirtualField(&$result) {
 /**
  * Returns a single field of the first of query results for a given SQL query, or false if empty.
  *
- * @param string $name Name of the field
- * @param string $sql SQL query
- * @return mixed Value of field read.
+ * @param string $name The name of the field to get.
+ * @param string $sql The SQL query.
+ * @return mixed Value of field read, or false if not found.
  */
 	public function field($name, $sql) {
 		$data = $this->fetchRow($sql);

lib/Cake/Model/Model.php

@@ -1636,13 +1636,13 @@ public function read($fields = null, $id = null) {
 	}
 
 /**
- * Returns the contents of a single field given the supplied conditions, in the
- * supplied order.
+ * Returns the content of a single field given the supplied conditions,
+ * of the first record in the supplied order.
  *
- * @param string $name Name of field to get
- * @param array $conditions SQL conditions (defaults to NULL)
- * @param string $order SQL ORDER BY fragment
- * @return string field contents, or false if not found
+ * @param string $name The name of the field to get.
+ * @param array $conditions SQL conditions (defaults to NULL).
+ * @param string $order SQL ORDER BY fragment.
+ * @return string|false Field content, or false if not found.
  * @link http://book.cakephp.org/2.0/en/models/retrieving-your-data.html#model-field
  */
 	public function field($name, $conditions = null, $order = null) {