docs: explain defaults/where behavior for find/create (#11069)

docs/models-usage.md

@@ -36,6 +36,8 @@ The method `findOrCreate` can be used to check if a certain element already exis
 
 
 Let's assume we have an empty database with a `User` model which has a `username` and a `job`.
 Let's assume we have an empty database with a `User` model which has a `username` and a `job`.
 
 
+`where` option will be appended to `defaults` for create case. 
+
 ```js
 ```js
 User
 User
   .findOrCreate({where: {username: 'sdepold'}, defaults: {job: 'Technical Lead JavaScript'}})
   .findOrCreate({where: {username: 'sdepold'}, defaults: {job: 'Technical Lead JavaScript'}})

lib/model.js

@@ -2221,7 +2221,7 @@ class Model {
    * The successful result of the promise will be (instance, built)
    * The successful result of the promise will be (instance, built)
    *
    *
    * @param {Object}   options find options
    * @param {Object}   options find options
-   * @param {Object}   options.where A hash of search attributes.
+   * @param {Object}   options.where A hash of search attributes. If `where` is a plain object it will be appended with defaults to build a new instance.
    * @param {Object}   [options.defaults] Default values to use if building a new instance
    * @param {Object}   [options.defaults] Default values to use if building a new instance
    * @param {Object}   [options.transaction] Transaction to run query under
    * @param {Object}   [options.transaction] Transaction to run query under
    *
    *
@@ -2265,7 +2265,7 @@ class Model {
    * {@link Model.findAll} for a full specification of find and options
    * {@link Model.findAll} for a full specification of find and options
    *
    *
    * @param {Object}      options find and create options
    * @param {Object}      options find and create options
-   * @param {Object}      options.where where A hash of search attributes.
+   * @param {Object}      options.where where A hash of search attributes. If `where` is a plain object it will be appended with defaults to build a new instance.
    * @param {Object}      [options.defaults] Default values to use if creating a new instance
    * @param {Object}      [options.defaults] Default values to use if creating a new instance
    * @param {Transaction} [options.transaction] Transaction to run query under
    * @param {Transaction} [options.transaction] Transaction to run query under
    *
    *
@@ -2375,7 +2375,7 @@ class Model {
    * {@link Model.findAll} for a full specification of find and options
    * {@link Model.findAll} for a full specification of find and options
    *
    *
    * @param {Object} options find options
    * @param {Object} options find options
-   * @param {Object} options.where A hash of search attributes.
+   * @param {Object} options.where A hash of search attributes. If `where` is a plain object it will be appended with defaults to build a new instance.
    * @param {Object} [options.defaults] Default values to use if creating a new instance
    * @param {Object} [options.defaults] Default values to use if creating a new instance
    *
    *
    * @returns {Promise<Model,boolean>}
    * @returns {Promise<Model,boolean>}