Improve API docs for a few table methods.

I read through the API docs for ORM\Table. I felt that these methods
needed a bit more detail than they currrently had.

src/ORM/Table.php

@@ -626,7 +626,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
     /**
      * Returns the behavior registry for this table.
      *
-     * @return \Cake\ORM\BehaviorRegistry
+     * @return \Cake\ORM\BehaviorRegistry The BehaviorRegistry instance.
      */
     public function behaviors()
     {
@@ -637,7 +637,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      * Check if a behavior with the given alias has been loaded.
      *
      * @param string $name The behavior alias to check.
-     * @return bool
+     * @return bool Whether or not the behavior exists.
      */
     public function hasBehavior($name)
     {
@@ -647,8 +647,8 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
     /**
      * Returns an association object configured for the specified alias if any
      *
-     * @param string $name the alias used for the association
-     * @return \Cake\ORM\Association
+     * @param string $name the alias used for the association.
+     * @return \Cake\ORM\Association|null Either the association or null.
      */
     public function association($name)
     {
@@ -658,7 +658,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
     /**
      * Get the associations collection for this table.
      *
-     * @return \Cake\ORM\AssociationCollection
+     * @return \Cake\ORM\AssociationCollection The collection of association objects.
      */
     public function associations()
     {
@@ -867,6 +867,11 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
     /**
      * {@inheritDoc}
      *
+     * ### Model.beforeFind event
+     *
+     * Each find() will trigger a `Model.beforeFind` event for all attached
+     * listeners. Any listener can set a valid result set using $query
+     *
      * By default, `$options` will recognize the following keys:
      *
      * - fields
@@ -879,7 +884,40 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      * - having
      * - contain
      * - join
-     * @return \Cake\ORM\Query
+     *
+     * ### Usage
+     *
+     * Using the options array:
+     *
+     * ```
+     * $query = $articles->find('all', [
+     *   'conditions' => ['published' => 1],
+     *   'limit' => 10,
+     *   'contain' => ['Users', 'Comments']
+     * ]);
+     * ```
+     *
+     * Using the builder interface:
+     *
+     * ```
+     * $query = $articles->find()
+     *   ->where(['published' => 1])
+     *   ->limit(10)
+     *   ->contain(['Users', 'Comments']);
+     * ```
+     *
+     * ### Calling finders
+     *
+     * The find() method is the entry point for custom finder methods.
+     * You can invoke a finder by specifying the type:
+     *
+     * ```
+     * $query = $articles->find('published');
+     * ```
+     *
+     * Would invoke the `findPublished` method.
+     *
+     * @return \Cake\ORM\Query The query builder
      */
     public function find($type = 'all', $options = [])
     {
@@ -889,11 +927,14 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
     }
 
     /**
-     * Returns the query as passed
+     * Returns the query as passed.
+     *
+     * By default findAll() applies no conditions, you
+     * can override this method in subclasses to modify how `find('all')` works.
      *
      * @param \Cake\ORM\Query $query The query to find with
      * @param array $options The options to use for the find
-     * @return \Cake\ORM\Query
+     * @return \Cake\ORM\Query The query builder
      */
     public function findAll(Query $query, array $options)
     {
@@ -955,7 +996,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      *
      * @param \Cake\ORM\Query $query The query to find with
      * @param array $options The options for the find
-     * @return \Cake\ORM\Query
+     * @return \Cake\ORM\Query The query builder
      */
     public function findList(Query $query, array $options)
     {
@@ -1022,7 +1063,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      *
      * @param \Cake\ORM\Query $query The query to find with
      * @param array $options The options to find with
-     * @return \Cake\ORM\Query
+     * @return \Cake\ORM\Query The qury builder
      */
     public function findThreaded(Query $query, array $options)
     {
@@ -1085,6 +1126,14 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
     /**
      * {@inheritDoc}
      *
+     * ### Usage
+     *
+     * Get an article and some relationships:
+     *
+     * ```
+     * $article = $articles->get(1, ['contain' => ['Users', 'Comments']]);
+     * ```
+     *
      * @throws \Cake\Datasource\Exception\InvalidPrimaryKeyException When $primaryKey has an
      *      incorrect number of elements.
      */
@@ -1134,9 +1183,13 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      * Finds an existing record or creates a new one.
      *
      * Using the attributes defined in $search a find() will be done to locate
-     * an existing record. If that record exists it will be returned. If it does
-     * not exist, a new entity will be created with the $search properties, and
-     * the $defaults. When a new entity is created, it will be saved.
+     * an existing record. If records matches the conditions, the first record
+     * will be returned.
+     *
+     * If no record can be found, a new entity will be created
+     * with the $search properties. If a callback is provided, it will be
+     * called allowing you to define additional default values. The new
+     * entity will be saved and returned.
      *
      * @param array $search The criteria to find existing records by.
      * @param callable|null $callback A callback that will be invoked for newly
@@ -1214,7 +1267,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      *
      * ### Options
      *
-     * The options array can receive the following keys:
+     * The options array accepts the following keys:
      *
      * - atomic: Whether to execute the save and callbacks inside a database
      *   transaction (default: true)
@@ -1237,7 +1290,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      * - Model.beforeRules: Will be triggered right before any rule checking is done
      *   for the passed entity if the `checkRules` key in $options is not set to false.
      *   Listeners will receive as arguments the entity, options array and the operation type.
-     *   If the event is stopped the checking result will be set to the result of the event itself.
+     *   If the event is stopped the rules check result will be set to the result of the event itself.
      * - Model.afterRules: Will be triggered right after the `checkRules()` method is
      *   called for the entity. Listeners will receive as arguments the entity,
      *   options array, the result of checking the rules and the operation type.
@@ -2079,6 +2132,19 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      * Override this method if you need to add non-conventional event listeners.
      * Or if you want you table to listen to non-standard events.
      *
+     * The conventional method map is:
+     *
+     * - Model.beforeMarshal => beforeMarshal
+     * - Model.beforeFind => beforeFind
+     * - Model.beforeSave => beforeSave
+     * - Model.afterSave => afterSave
+     * - Model.afterSaveCommit => afterSaveCommit
+     * - Model.beforeDelete => beforeDelete
+     * - Model.afterDelete => afterDelete
+     * - Model.afterDeleteCommit => afterDeleteCommit
+     * - Model.beforeRules => beforeRules
+     * - Model.afterRules => afterRules
+     *
      * @return array
      */
     public function implementedEvents()