Merge pull request #3717 from BridgeAR/master

Fix lock docs

lib/model.js

@@ -680,7 +680,7 @@ module.exports = (function() {
    * @param  {Number}                    [options.limit]
    * @param  {Number}                    [options.offset]
    * @param  {Transaction}               [options.transaction]
-   * @param  {String}                    [options.lock] Lock the selected rows in either share or update mode. Possible options are transaction.LOCK.UPDATE and transaction.LOCK.SHARE. See [transaction.LOCK for an example](https://github.com/sequelize/sequelize/wiki/API-Reference-Transaction#LOCK)
+   * @param  {String|Object}             [options.lock] Lock the selected rows. Possible options are transaction.LOCK.UPDATE and transaction.LOCK.SHARE. Postgres also supports transaction.LOCK.KEY_SHARE, transaction.LOCK.NO_KEY_UPDATE and specific model locks with joins. See [transaction.LOCK for an example](api/transaction#lock)
    * @param  {Boolean}                   [options.raw] Return raw result. See sequelize.query for more information.
    *
    * @see    {Sequelize#query}

lib/transaction.js

@@ -55,16 +55,36 @@ Transaction.ISOLATION_LEVELS = {
  *
  * ```js
  * t1 // is a transaction
+ * t1.LOCK.UPDATE,
+ * t1.LOCK.SHARE,
+ * t1.LOCK.KEY_SHARE, // Postgres 9.3+ only
+ * t1.LOCK.NO_KEY_UPDATE // Postgres 9.3+ only
+ * ```
+ * 
+ * Usage:
+ * ```js
+ * t1 // is a transaction
  * Model.findAll({
- *   where: ...
- * }, {
+ *   where: ...,
+ *   transaction: t1,
+ *   lock: t1.LOCK...
+ * });
+ * ```
+ * 
+ * Postgres also supports specific locks while eager loading by using OF:
+ * ```js
+ * UserModel.findAll({
+ *   where: ...,
+ *   include: [TaskModel, ...],
  *   transaction: t1,
- *   lock: t1.LOCK.UPDATE,
- *   lock: t1.LOCK.SHARE,
- *   lock: t1.LOCK.KEY_SHARE, // Postgres 9.3+ only
- *   lock: t1.LOCK.NO_KEY_UPDATE // Postgres 9.3+ only
- * })
+ *   lock: {
+ *     level: t1.LOCK...,
+ *     of: UserModel
+ *   }
+ * });
  * ```
+ * UserModel will be locked but TaskModel won't!
+ * 
  * @property LOCK
  */
 Transaction.LOCK = Transaction.prototype.LOCK = {