From 1af03613cc9a5e7539e417ff8b1b784450a1eb21 Mon Sep 17 00:00:00 2001
From: Rand McKinney <rand@strongloop.com>
Date: Tue, 22 Dec 2015 16:35:33 -0800
Subject: [PATCH] Update persisted-model.js

- Correct doc for findOrCreate.
- Fix indentation
- Remove quotes in example `where`
- Fix typo
- Fix spacing in notional where clause
---
 lib/persisted-model.js | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/lib/persisted-model.js b/lib/persisted-model.js
index b3bb6228..e60c0c26 100644
--- a/lib/persisted-model.js
+++ b/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'}`
-   * <br/>see
-   * [Where filter](https://docs.strongloop.com/display/LB/Where+filter#Wherefilter-Whereclauseforothermethods).
+   * @options {Object} [filter] Optional Filter object; see below.
+   * @property {String|Object|Array} fields Identify fields to include in return result.
+   * <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).