Fixup JSDocs; note: updateOrCreate function alias pulled out on separate line for docs

lib/models/data-model.js

@@ -73,14 +73,12 @@ function convertNullToNotFoundError(ctx, cb) {
 }
 
 /**
- * Create new instance of Model class, saved in database
+ * Create new instance of Model class, saved in database.
  *
- * @param data [optional]
- * @param callback(err, obj)
- * callback called with arguments:
- *
- *   - err (null or Error)
- *   - instance (null or Model)
+ * @param {Object} [data] Object containing model instance data.
+ * @callback {Function} callback Callback function; see below.
+ * @param {Error|null} err Error object
+ * @param {Model|null} Model instance 
  */
 
 DataModel.create = function (data, callback) {
@@ -100,10 +98,15 @@ setRemoting(DataModel.create, {
  * @param {Function} [callback] The callback function
  */
 
-DataModel.upsert = DataModel.updateOrCreate = function upsert(data, callback) {
+DataModel.upsert =  function upsert(data, callback) {
   throwNotAttached(this.modelName, 'updateOrCreate');
 };
 
+/**
+ * Alias for upsert function.
+ */
+DataModel.updateOrCreate = DataModel.upsert;
+
 // upsert ~ remoting attributes
 setRemoting(DataModel.upsert, {
   description: 'Update an existing model instance or insert a new one into the data source',
@@ -113,8 +116,8 @@ setRemoting(DataModel.upsert, {
 });
 
 /**
- * Find one record, same as `all`, limited by 1 and return object, not collection,
- * if not found, create using data provided as second argument
+ * Find one record instance, same as `all`, limited by one and return object, not collection.
+ * If not found, create the record using data provided as second argument.
  *
  * @param {Object} query - search conditions: {where: {test: 'me'}}.
  * @param {Object} data - object to create.
@@ -126,7 +129,7 @@ DataModel.findOrCreate = function findOrCreate(query, data, callback) {
 };
 
 /**
- * Check whether a model instance exists in database
+ * Check whether a model instance exists in database.
  *
  * @param {id} id - identifier of object (primary key value)
  * @param {Function} cb - callbacl called with (err, exists: Bool)
@@ -263,10 +266,15 @@ setRemoting(DataModel.count, {
 });
 
 /**
- * Save instance. When instance haven't id, create method called instead.
- * Triggers: validate, save, update | create
- * @param options {validate: true, throws: false} [optional]
- * @param callback(err, obj)
+ * Save instance. When instance does not have an ID, create method instead.
+ * Triggers: validate, save, update or create.
+ * 
+ * @options [options] Options
+ * @property {Boolean} validate Whether to validate.
+ * @property {Boolean} throws 
+ * @callback {Function} callback Callback function.
+ * @param {Error} err Error object
+ * @param {Object} 
  */
 
 DataModel.prototype.save = function (options, callback) {
@@ -290,7 +298,7 @@ DataModel.prototype.save = function (options, callback) {
 
 /**
  * Determine if the data model is new.
- * @returns {Boolean}
+ * @returns {Boolean} True if data model is new.
  */
 
 DataModel.prototype.isNewRecord = function () {
@@ -310,9 +318,8 @@ DataModel.prototype.destroy = function (cb) {
 };
 
 /**
- * Update single attribute
- *
- * equals to `updateAttributes({name: value}, cb)
+ * Update single attribute.
+ * Equivalent to `updateAttributes({name: value}, cb)`
  *
  * @param {String} name - name of property
  * @param {Mixed} value - value of property
@@ -326,7 +333,7 @@ DataModel.prototype.updateAttribute = function updateAttribute(name, value, call
 /**
  * Update set of attributes
  *
- * this method performs validation before updating
+ * Performs validation before updating
  *
  * @trigger `validation`, `save` and `update` hooks
  * @param {Object} data - data to update
@@ -349,7 +356,9 @@ setRemoting(DataModel.prototype.updateAttributes, {
  * Reload object from persistence
  *
  * @requires `id` member of `object` to be able to call `find`
- * @param {Function} callback - called with (err, instance) arguments
+ * @callback {Function} callback Callback function
+ * @param {Error} err
+ * @param {Object} instance 
  */
 
 DataModel.prototype.reload = function reload(callback) {