Merge pull request #2360 from strongloop/doc/replace

Docuemtation for `replace*` methods

lib/persisted-model.js

@@ -115,6 +115,22 @@ module.exports = function(registry) {
     throwNotAttached(this.modelName, 'upsert');
   };
 
+  /**
+   * Replace or insert a model instance; replace existing record if one is found,
+   * such that parameter `data.id` matches `id` of model instance; otherwise,
+   * insert a new record.
+   * @param {Object} data The model instance data.
+   * @options {Object} [options] Options for replaceOrCreate
+   * @property {Boolean} validate Perform validation before saving.  Default is true.
+   * @callback {Function} callback Callback function called with `cb(err, obj)` signature.
+   * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
+   * @param {Object} model Replaced model instance.
+   */
+
+  PersistedModel.replaceOrCreate = function replaceOrCreate(data, callback) {
+    throwNotAttached(this.modelName, 'replaceOrCreate');
+  };
+
   /**
    * Finds one record matching the optional filter object. If not found, creates
    * the object using the data provided as second argument. In this sense it is
@@ -482,6 +498,40 @@ module.exports = function(registry) {
     throwNotAttached(this.modelName, 'updateAttributes');
   };
 
+  /**
+   * Replace attributes for a model instance and persist it into the datasource.
+   * Performs validation before replacing.
+   *
+   * @param {Object} data Data to replace.
+   * @options {Object} [options] Options for replace
+   * @property {Boolean} validate Perform validation before saving.  Default is true.
+   * @callback {Function} callback Callback function called with `(err, instance)` arguments.
+   * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
+   * @param {Object} instance Replaced instance.
+   */
+
+  PersistedModel.prototype.replaceAttributes = function replaceAttributes(data, cb) {
+    throwNotAttached(this.modelName, 'replaceAttributes');
+  };
+
+  /**
+   * Replace attributes for a model instance whose id is the first input
+   * argument and persist it into the datasource.
+   * Performs validation before replacing.
+   *
+   * @param {*} id The ID value of model instance to replace.
+   * @param {Object} data Data to replace.
+   * @options {Object} [options] Options for replace
+   * @property {Boolean} validate Perform validation before saving.  Default is true.
+   * @callback {Function} callback Callback function called with `(err, instance)` arguments.
+   * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
+   * @param {Object} instance Replaced instance.
+   */
+
+  PersistedModel.replaceById = function replaceById(id, data, cb) {
+    throwNotAttached(this.modelName, 'replaceById');
+  };
+
   /**
    * Reload object from persistence.  Requires `id` member of `object` to be able to call `find`.
    * @callback {Function} callback Callback function called with `(err, instance)` arguments.  Required.