Adding some additional documentation for Model::find(). Fixes #952

cake/libs/model/model.php

@@ -1997,7 +1997,7 @@ class Model extends Overloadable {
 	}
 
 /**
- * Returns a result set array.
+ * Queries the datasource and returns a result set array.
  *
  * Also used to perform new-notation finds, where the first argument is type of find operation to perform
  * (all / first / count / neighbors / list / threaded ),
@@ -2015,6 +2015,24 @@ class Model extends Overloadable {
  * ));
  * }}}
  *
+ * In addition to the standard query keys above, you can provide Datasource, and behavior specific
+ * keys.  For example, when using a SQL based datasource you can use the joins key to specify additional
+ * joins that should be part of the query.
+ *
+ * {{{
+ * find('all', array(
+ * 		'conditions' => array('name' => 'Thomas Anderson'),
+ * 		'joins' => array(
+ * 			'alias' => 'Thought',
+ * 			'table' => 'thoughts',
+ * 			'type' => 'LEFT',
+ * 			'conditions' => '`Thought`.`person_id` = `Person`.`id`'
+ * 		)
+ * ));
+ * }}}
+ *
+ * Behaviors and find types can also define custom finder keys which are passed into find().
+ *
  * Specifying 'fields' for new-notation 'list':
  *
  *  - If no fields are specified, then 'id' is used for key and 'model->displayField' is used for value.