Merge pull request #1910 from strongloop/fix-findOrCreate-doc

Update persisted-model.js

lib/persisted-model.js

@@ -111,13 +111,31 @@ module.exports = function(registry) {
   };
 
   /**
-   * Find one record matching the optional `where` filter. The same as `find`, but limited to one object.
+   * 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 the same as `find`, but limited to one object.
    * Returns an object, not collection.
-   * If not found, create the object using data provided as second argument.
+   * 
+   * If you don't provide the filter object argument, it tries to locate an existing object that
+   * matches the `data` argument. 
    *
-   * @param {Object} where Where clause, such as `{test: 'me'}`
+   * @options {Object} [filter] Optional Filter object; see below.
-   * <br/>see
+   * @property {String|Object|Array} fields Identify fields to include in return result.
-   * [Where filter](https://docs.strongloop.com/display/LB/Where+filter#Wherefilter-Whereclauseforothermethods).
+   * <br/>See [Fields filter](http://docs.strongloop.com/display/LB/Fields+filter).
+   * @property {String|Object|Array} include  See PersistedModel.include documentation.
+   * <br/>See [Include filter](http://docs.strongloop.com/display/LB/Include+filter).
+   * @property {Number} limit Maximum number of instances to return.
+   * <br/>See [Limit filter](http://docs.strongloop.com/display/LB/Limit+filter).
+   * @property {String} order Sort order: either "ASC" for ascending or "DESC" for descending.
+   * <br/>See [Order filter](http://docs.strongloop.com/display/LB/Order+filter).
+   * @property {Number} skip Number of results to skip.
+   * <br/>See [Skip filter](http://docs.strongloop.com/display/LB/Skip+filter).
+   * @property {Object} where Where clause, like
+   * ```
+   * {where: {key: val, key2: {gt: val2}, ...}}
+   * ```
+   * <br/>See
+   * [Where filter](https://docs.strongloop.com/display/LB/Where+filter#Wherefilter-Whereclauseforqueries).
    * @param {Object} data Data to insert if object matching the `where` filter is not found.
    * @callback {Function} callback Callback function called with `cb(err, instance)` arguments.  Required.
    * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).