Try to clarify adding and setting associations (#5630)

* Try to clarify adding and setting associations

lib/associations/belongs-to-many.js

@@ -211,7 +211,7 @@ var BelongsToMany = function(source, target, options) {
     /**
     /**
      * Set the associated models by passing an array of instances or their primary keys. Everything that it not in the passed array will be un-associated.
      * Set the associated models by passing an array of instances or their primary keys. Everything that it not in the passed array will be un-associated.
      *
      *
-     * @param {Array<Instance|String|Number>} [newAssociations] An array of instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations.
+     * @param {Array<Instance|String|Number>} [newAssociations] An array of persisted instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations.
      * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate`, `update` and `destroy`. Can also hold additional attributes for the join table
      * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate`, `update` and `destroy`. Can also hold additional attributes for the join table
      * @param {Object} [options.validate] Run validation for the join model
      * @param {Object} [options.validate] Run validation for the join model
      * @return {Promise}
      * @return {Promise}
@@ -219,9 +219,9 @@ var BelongsToMany = function(source, target, options) {
      */
      */
     set: 'set' + plural,
     set: 'set' + plural,
     /**
     /**
-     * Associate several instances with this.
+     * Associate several persisted instances with this.
      *
      *
-     * @param {Array<Instance|String|Number>} [newAssociations] An array of instances or primary key of instances to associate with this.
+     * @param {Array<Instance|String|Number>} [newAssociations] An array of persisted instances or primary key of instances to associate with this.
      * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate` and `update`. Can also hold additional attributes for the join table.
      * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate` and `update`. Can also hold additional attributes for the join table.
      * @param {Object} [options.validate] Run validation for the join model.
      * @param {Object} [options.validate] Run validation for the join model.
      * @return {Promise}
      * @return {Promise}
@@ -229,9 +229,9 @@ var BelongsToMany = function(source, target, options) {
      */
      */
     addMultiple: 'add' + plural,
     addMultiple: 'add' + plural,
     /**
     /**
-     * Associate one instance with this.
+     * Associate a persisted instance with this.
      *
      *
-     * @param {Instance|String|Number} [newAssociation] An instance or primary key of instance to associate with this.
+     * @param {Instance|String|Number} [newAssociation] A persisted instance or primary key of instance to associate with this.
      * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate` and `update`. Can also hold additional attributes for the join table.
      * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate` and `update`. Can also hold additional attributes for the join table.
      * @param {Object} [options.validate] Run validation for the join model.
      * @param {Object} [options.validate] Run validation for the join model.
      * @return {Promise}
      * @return {Promise}

lib/associations/belongs-to.js

@@ -84,7 +84,7 @@ var BelongsTo = function(source, target, options) {
     /**
     /**
      * Set the associated model.
      * Set the associated model.
      *
      *
-     * @param {Instance|String|Number} [newAssociation] An instance or the primary key of an instance to associate with this. Pass `null` or `undefined` to remove the association.
+     * @param {Instance|String|Number} [newAssociation] An persisted instance or the primary key of an instance to associate with this. Pass `null` or `undefined` to remove the association.
      * @param {Object} [options] Options passed to `this.save`
      * @param {Object} [options] Options passed to `this.save`
      * @param {Boolean} [options.save=true] Skip saving this after setting the foreign key if false.
      * @param {Boolean} [options.save=true] Skip saving this after setting the foreign key if false.
      * @return {Promise}
      * @return {Promise}

lib/associations/has-many.js

@@ -103,9 +103,9 @@ var HasMany = function(source, target, options) {
      */
      */
     get: 'get' + plural,
     get: 'get' + plural,
     /**
     /**
-     * Set the associated models by passing an array of instances or their primary keys. Everything that is not in the passed array will be un-associated
+     * Set the associated models by passing an array of persisted instances or their primary keys. Everything that is not in the passed array will be un-associated
      *
      *
-     * @param {Array<Instance|String|Number>} [newAssociations] An array of instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations.
+     * @param {Array<Instance|String|Number>} [newAssociations] An array of persisted instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations.
      * @param {Object} [options] Options passed to `target.findAll` and `update`.
      * @param {Object} [options] Options passed to `target.findAll` and `update`.
      * @param {Object} [options.validate] Run validation for the join model
      * @param {Object} [options.validate] Run validation for the join model
      * @return {Promise}
      * @return {Promise}
@@ -113,9 +113,9 @@ var HasMany = function(source, target, options) {
      */
      */
     set: 'set' + plural,
     set: 'set' + plural,
     /**
     /**
-     * Associate several instances with this.
+     * Associate several persisted instances with this.
      *
      *
-     * @param {Array<Instance|String|Number>} [newAssociations] An array of instances or primary key of instances to associate with this.
+     * @param {Array<Instance|String|Number>} [newAssociations] An array of persisted instances or primary key of instances to associate with this.
      * @param {Object} [options] Options passed to `target.update`.
      * @param {Object} [options] Options passed to `target.update`.
      * @param {Object} [options.validate] Run validation for the join model.
      * @param {Object} [options.validate] Run validation for the join model.
      * @return {Promise}
      * @return {Promise}
@@ -123,9 +123,9 @@ var HasMany = function(source, target, options) {
      */
      */
     addMultiple: 'add' + plural,
     addMultiple: 'add' + plural,
     /**
     /**
-     * Associate one instance with this.
+     * Associate a persisted instance with this.
      *
      *
-     * @param {Instance|String|Number} [newAssociation] An instance or primary key of instance to associate with this.
+     * @param {Instance|String|Number} [newAssociation] A persisted instance or primary key of instance to associate with this.
      * @param {Object} [options] Options passed to `target.update`.
      * @param {Object} [options] Options passed to `target.update`.
      * @param {Object} [options.validate] Run validation for the join model.
      * @param {Object} [options.validate] Run validation for the join model.
      * @return {Promise}
      * @return {Promise}

lib/associations/has-one.js

@@ -79,7 +79,7 @@ var HasOne = function(srcModel, targetModel, options) {
     /**
     /**
      * Set the associated model.
      * Set the associated model.
      *
      *
-     * @param {Instance|String|Number} [newAssociation] An instance or the primary key of an instance to associate with this. Pass `null` or `undefined` to remove the association.
+     * @param {Instance|String|Number} [newAssociation] An persisted instance or the primary key of a persisted instance to associate with this. Pass `null` or `undefined` to remove the association.
      * @param {Object} [options] Options passed to getAssociation and `target.save`
      * @param {Object} [options] Options passed to getAssociation and `target.save`
      * @return {Promise}
      * @return {Promise}
      * @method setAssociation
      * @method setAssociation