diff --git a/lib/persisted-model.js b/lib/persisted-model.js
index b3bb6228..ab17ef16 100644
--- a/lib/persisted-model.js
+++ b/lib/persisted-model.js
@@ -111,13 +111,29 @@ module.exports = function(registry) {
   };
 
   /**
-   * Find one record matching the optional `where` filter. 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.
+   * 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 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).