[ci skip] 📝 Merge pull request #3922 from phanect/master

Add missing parameter to the JSDoc of findOrCreate

lib/model.js

@@ -1133,7 +1133,7 @@ Model.prototype.all = function(options) {
  * @param  {String|Array|Sequelize.fn} [options.order] Specifies an ordering. If a string is provided, it will be escaped. Using an array, you can provide several columns / functions to order by. Each element can be further wrapped in a two-element array. The first element is the column / function to order by, the second is the direction. For example: `order: [['name', 'DESC']]`. In this way the column will be escaped, but the direction will not.
  * @param  {String|Array|Sequelize.fn} [options.order] Specifies an ordering. If a string is provided, it will be escaped. Using an array, you can provide several columns / functions to order by. Each element can be further wrapped in a two-element array. The first element is the column / function to order by, the second is the direction. For example: `order: [['name', 'DESC']]`. In this way the column will be escaped, but the direction will not.
  * @param  {Number}                    [options.limit]
  * @param  {Number}                    [options.limit]
  * @param  {Number}                    [options.offset]
  * @param  {Number}                    [options.offset]
- * @param  {Transaction}               [options.transaction]
+ * @param  {Transaction}               [options.transaction] Transaction to run query under
  * @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  {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.
  * @param  {Boolean}                   [options.raw] Return raw result. See sequelize.query for more information.
  * @param  {Function}                  [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param  {Function}                  [options.logging=false] A function that gets executed while running the query to log the sql.
@@ -1215,7 +1215,7 @@ Model.prototype.findAll = function(options) {
 *
 *
 * @param  {Number|String|Buffer}      [options] A hash of options to describe the scope of the search, or a number to search by id.
 * @param  {Number|String|Buffer}      [options] A hash of options to describe the scope of the search, or a number to search by id.
 * @param  {Object}             '      [options]
 * @param  {Object}             '      [options]
-* @param  {Transaction}               [options.transaction]
+* @param  {Transaction}               [options.transaction] Transaction to run query under
 *
 *
 * @see {Model#findAll}           for an explanation of options
 * @see {Model#findAll}           for an explanation of options
 * @return {Promise<Instance>}
 * @return {Promise<Instance>}
@@ -1249,7 +1249,7 @@ Model.prototype.findByPrimary = Model.prototype.findById;
 * Search for a single instance. This applies LIMIT 1, so the listener will always be called with a single instance.
 * Search for a single instance. This applies LIMIT 1, so the listener will always be called with a single instance.
 *
 *
 * @param  {Object}                    [options] A hash of options to describe the scope of the search
 * @param  {Object}                    [options] A hash of options to describe the scope of the search
-* @param  {Transaction}               [options.transaction]
+* @param  {Transaction}               [options.transaction] Transaction to run query under
 *
 *
 * @see {Model#findAll}           for an explanation of options
 * @see {Model#findAll}           for an explanation of options
 * @return {Promise<Instance>}
 * @return {Promise<Instance>}
@@ -1282,7 +1282,7 @@ Model.prototype.find = Model.prototype.findOne;
  * @param {Function}        [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {Function}        [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {DataType|String} [options.dataType] The type of the result. If `field` is a field in this Model, the default will be the type of that field, otherwise defaults to float.
  * @param {DataType|String} [options.dataType] The type of the result. If `field` is a field in this Model, the default will be the type of that field, otherwise defaults to float.
  * @param {boolean}         [options.distinct] Applies DISTINCT to the field being aggregated over
  * @param {boolean}         [options.distinct] Applies DISTINCT to the field being aggregated over
- * @param {Transaction}     [options.transaction]
+ * @param {Transaction}     [options.transaction] Transaction to run query under
  * @param {boolean}         [options.plain] When `true`, the first returned value of `aggregateFunction` is cast to `dataType` and returned. If additional attributes are specified, along with `group` clauses, set `plain` to `false` to return all values of all returned rows.  Defaults to `true`
  * @param {boolean}         [options.plain] When `true`, the first returned value of `aggregateFunction` is cast to `dataType` and returned. If additional attributes are specified, along with `group` clauses, set `plain` to `false` to return all values of all returned rows.  Defaults to `true`
  *
  *
  * @return {Promise<options.dataType|object>}                Returns the aggregate result cast to `options.dataType`, unless `options.plain` is false, in which case the complete data result is returned.
  * @return {Promise<options.dataType|object>}                Returns the aggregate result cast to `options.dataType`, unless `options.plain` is false, in which case the complete data result is returned.
@@ -1531,7 +1531,7 @@ Model.prototype.bulkBuild = function(valueSets, options) {
  * @param {Array}         [options.fields] If set, only columns matching those in fields will be saved
  * @param {Array}         [options.fields] If set, only columns matching those in fields will be saved
  * @param {Array}         [options.include] an array of include options - Used to build prefetched/included model instances
  * @param {Array}         [options.include] an array of include options - Used to build prefetched/included model instances
  * @param {String}        [options.onDuplicate]
  * @param {String}        [options.onDuplicate]
- * @param {Transaction}   [options.transaction]
+ * @param {Transaction}   [options.transaction] Transaction to run query under
  * @param {Function}      [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {Function}      [options.logging=false] A function that gets executed while running the query to log the sql.
  *
  *
  * @return {Promise<Instance>}
  * @return {Promise<Instance>}
@@ -1596,11 +1596,11 @@ Model.prototype.findOrInitialize = Model.prototype.findOrBuild = function(option
  * However, it is not always possible to handle this case in SQLite, specifically if one transaction inserts and another tries to select before the first one has comitted. In this case, an instance of sequelize.TimeoutError will be thrown instead.
  * However, it is not always possible to handle this case in SQLite, specifically if one transaction inserts and another tries to select before the first one has comitted. In this case, an instance of sequelize.TimeoutError will be thrown instead.
  * If a transaction is created, a savepoint will be created instead, and any unique constraint violation will be handled internally.
  * If a transaction is created, a savepoint will be created instead, and any unique constraint violation will be handled internally.
  *
  *
- * @param {Object}   options
- * @param {Object}   options.where where A hash of search attributes.
- * @param {Object}   [options.defaults] Default values to use if creating a new instance
- *
- * @see {Model#findAll} for a specification of find and options
+ * @param {Object}      options
+ * @param {Object}      options.where where A hash of search attributes.
+ * @param {Object}      [options.defaults] Default values to use if creating a new instance
+ * @param {Transaction} [options.transaction] Transaction to run query under
+ * @see {Model#findAll} for a full specification of find and options
  * @return {Promise<Instance,created>}
  * @return {Promise<Instance,created>}
  */
  */
 Model.prototype.findOrCreate = function(options) {
 Model.prototype.findOrCreate = function(options) {
@@ -1744,7 +1744,7 @@ Model.prototype.insertOrUpdate = Model.prototype.upsert;
  * @param  {Boolean}      [options.individualHooks=false]  Run before / after create hooks for each individual Instance? BulkCreate hooks will still be run if options.hooks is true.
  * @param  {Boolean}      [options.individualHooks=false]  Run before / after create hooks for each individual Instance? BulkCreate hooks will still be run if options.hooks is true.
  * @param  {Boolean}      [options.ignoreDuplicates=false] Ignore duplicate values for primary keys? (not supported by postgres)
  * @param  {Boolean}      [options.ignoreDuplicates=false] Ignore duplicate values for primary keys? (not supported by postgres)
  * @param  {Array}        [options.updateOnDuplicate]      Fields to update if row key already exists (on duplicate key update)? (only supported by mysql & mariadb). By default, all fields are updated.
  * @param  {Array}        [options.updateOnDuplicate]      Fields to update if row key already exists (on duplicate key update)? (only supported by mysql & mariadb). By default, all fields are updated.
- * @param  {Transaction}  [options.transaction]
+ * @param  {Transaction}  [options.transaction] Transaction to run query under
  * @param  {Function}     [options.logging=false]          A function that gets executed while running the query to log the sql.
  * @param  {Function}     [options.logging=false]          A function that gets executed while running the query to log the sql.
  *
  *
  * @return {Promise<Array<Instance>>}
  * @return {Promise<Array<Instance>>}
@@ -1889,7 +1889,7 @@ Model.prototype.bulkCreate = function(records, options) {
  * Truncate all instances of the model. This is a convenient method for Model.destroy({ truncate: true }).
  * Truncate all instances of the model. This is a convenient method for Model.destroy({ truncate: true }).
  *
  *
  * @param {object} [options] The options passed to Model.destroy in addition to truncate
  * @param {object} [options] The options passed to Model.destroy in addition to truncate
- * @param {Boolean|function} [options.transaction]
+ * @param {Boolean|function} [options.transaction] Transaction to run query under
  * @param {Boolean|function} [options.cascade = false] Only used in conjuction with TRUNCATE. Truncates  all tables that have foreign-key references to the named table, or to any tables added to the group due to CASCADE.
  * @param {Boolean|function} [options.cascade = false] Only used in conjuction with TRUNCATE. Truncates  all tables that have foreign-key references to the named table, or to any tables added to the group due to CASCADE.
  * @param {Boolean|function} [options.logging] A function that logs sql queries, or false for no logging
  * @param {Boolean|function} [options.logging] A function that logs sql queries, or false for no logging
  * @return {Promise}
  * @return {Promise}
@@ -1913,7 +1913,7 @@ Model.prototype.truncate = function(options) {
  * @param  {Boolean}      [options.force=false]           Delete instead of setting deletedAt to current timestamp (only applicable if `paranoid` is enabled)
  * @param  {Boolean}      [options.force=false]           Delete instead of setting deletedAt to current timestamp (only applicable if `paranoid` is enabled)
  * @param  {Boolean}      [options.truncate=false]        If set to true, dialects that support it will use TRUNCATE instead of DELETE FROM. If a table is truncated the where and limit options are ignored
  * @param  {Boolean}      [options.truncate=false]        If set to true, dialects that support it will use TRUNCATE instead of DELETE FROM. If a table is truncated the where and limit options are ignored
  * @param  {Boolean}      [options.cascade=false]         Only used in conjuction with TRUNCATE. Truncates  all tables that have foreign-key references to the named table, or to any tables added to the group due to CASCADE.
  * @param  {Boolean}      [options.cascade=false]         Only used in conjuction with TRUNCATE. Truncates  all tables that have foreign-key references to the named table, or to any tables added to the group due to CASCADE.
- * @param  {Transaction}  [options.transaction]
+ * @param  {Transaction}  [options.transaction] Transaction to run query under
  * @param  {Function}     [options.logging=false]         A function that gets executed while running the query to log the sql.
  * @param  {Function}     [options.logging=false]         A function that gets executed while running the query to log the sql.
  * @return {Promise<Integer>} The number of destroyed rows
  * @return {Promise<Integer>} The number of destroyed rows
  */
  */
@@ -1990,7 +1990,7 @@ Model.prototype.destroy = function(options) {
  * @param  {Boolean}      [options.individualHooks=false] If set to true, restore will find all records within the where parameter and will execute before / after bulkRestore hooks on each row
  * @param  {Boolean}      [options.individualHooks=false] If set to true, restore will find all records within the where parameter and will execute before / after bulkRestore hooks on each row
  * @param  {Number}       [options.limit]                 How many rows to undelete
  * @param  {Number}       [options.limit]                 How many rows to undelete
  * @param  {Function}     [options.logging=false]         A function that gets executed while running the query to log the sql.
  * @param  {Function}     [options.logging=false]         A function that gets executed while running the query to log the sql.
- * @param  {Transaction}  [options.transaction]
+ * @param  {Transaction}  [options.transaction] Transaction to run query under
  *
  *
  * @return {Promise<undefined>}
  * @return {Promise<undefined>}
  */
  */
@@ -2063,7 +2063,7 @@ Model.prototype.restore = function(options) {
  * @param  {Boolean}      [options.returning=false]       Return the affected rows (only for postgres)
  * @param  {Boolean}      [options.returning=false]       Return the affected rows (only for postgres)
  * @param  {Number}       [options.limit]                 How many rows to update (only for mysql and mariadb)
  * @param  {Number}       [options.limit]                 How many rows to update (only for mysql and mariadb)
  * @param  {Function}     [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param  {Function}     [options.logging=false] A function that gets executed while running the query to log the sql.
- * @param  {Transaction}  [options.transaction]
+ * @param  {Transaction}  [options.transaction] Transaction to run query under
  *
  *
  * @return {Promise<Array<affectedCount,affectedRows>>}
  * @return {Promise<Array<affectedCount,affectedRows>>}
  */
  */