verdnatura-mirror
/
loopback
mirror of https://github.com/strongloop/loopback.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix API docs to add proper callback doc per #1041

This commit is contained in:
crandmck 2015-02-10 15:13:55 -08:00
parent 9816999864
commit 538e9f0c62
1 changed files with 103 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
lib/persisted-model.js
View File

@ -78,11 +78,13 @@ function convertNullToNotFoundError(ctx, cb) {
} }
/** /**
* Create new instance of Model class, saved in database * Create new instance of Model, and save to database.
* *
* @param {Object}|[{Object}] data Optional data object. Can be either a single model instance or an array of instances. * @param {Object}|[{Object}] data Optional data argument. Can be either a single model instance or an array of instances.
* @param {Function} cb Callback function with `cb(err, obj)` signature, *
* where `err` is error object and `obj` is null or Model instance. * @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} models Model instances or null.
*/ */
PersistedModel.create = function(data, callback) { PersistedModel.create = function(data, callback) {
@ -91,8 +93,10 @@ PersistedModel.create = function(data, callback) {
/** /**
* Update or insert a model instance * Update or insert a model instance
* @param {Object} data The model instance data * @param {Object} data The model instance data to insert.
* @param {Function} [callback] The callback function * @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 Updated model instance.
*/ */
PersistedModel.upsert = PersistedModel.updateOrCreate = function upsert(data, callback) { PersistedModel.upsert = PersistedModel.updateOrCreate = function upsert(data, callback) {
@ -100,13 +104,16 @@ PersistedModel.upsert = PersistedModel.updateOrCreate = function upsert(data, ca
}; };
/** /**
* Find one record, same as `find`, but limited to one object. Returns an object, not collection. * 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. * If not found, create the object using data provided as second argument.
* *
* @param {Object} where Where clause, such as `{where: {test: 'me'}}` * @param {Object} where Where clause, such as `{where: {test: 'me'}}`
* <br/>see [Where filter](http://docs.strongloop.com/display/public/LB/Where+filter). * <br/>see [Where filter](http://docs.strongloop.com/display/public/LB/Where+filter).
* @param {Object} data Object to create. * @param {Object} data Data to insert if object matching the `where` filter is not found.
* @param {Function} cb Callback called with `cb(err, instance)` signature. * @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).
* @param {Object} instance Model instance matching the `where` filter, if found.
*/ */
PersistedModel.findOrCreate = function findOrCreate(query, data, callback) { PersistedModel.findOrCreate = function findOrCreate(query, data, callback) {
@ -118,8 +125,11 @@ PersistedModel.findOrCreate._delegate = true;
/** /**
* 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 {id} id Identifier of object (primary key value).
* @param {Function} cb Callback function called with `(err, exists: Bool)` *
* @callback {Function} callback Callback function called with `(err, exists)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Boolean} exists True if the instance with the specified ID exists; false otherwise.
*/ */
PersistedModel.exists = function exists(id, cb) { PersistedModel.exists = function exists(id, cb) {
@ -129,8 +139,11 @@ PersistedModel.exists = function exists(id, cb) {
/** /**
* Find object by ID. * Find object by ID.
* *
* @param {*} id - primary key value * @param {*} id Primary key value
* @param {Function} cb Callback function called with `(err, instances)`. Required. * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Object} instance Model instance matching the specified ID or null if no instance matches.
*/ */
PersistedModel.findById = function find(id, cb) { PersistedModel.findById = function find(id, cb) {
@ -158,10 +171,9 @@ PersistedModel.findById = function find(id, cb) {
* ``` * ```
* <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter). * <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
* *
* @param {Function} Callback function called with `(err, returned-instances)`. * @callback {Function} callback Callback function called with `(err, returned-instances)` arguments. Required.
* @callback {Function} callback * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Error} err * @param {Array} models Model instances matching the filter, or null if none found.
* @param {Array} models Model instances matching the filter
*/ */
PersistedModel.find = function find(params, cb) { PersistedModel.find = function find(params, cb) {
@ -187,9 +199,10 @@ PersistedModel.find = function find(params, cb) {
* { key: val, key2: {gt: 'val2'}, ...} * { key: val, key2: {gt: 'val2'}, ...}
* ``` * ```
* <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter). * <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
* *
* @param {Function} Callback function called with `(err, returned-instance)`. Required. * @callback {Function} callback Callback function called with `(err, returned-instance)` arguments. Required.
* @returns {Object} First model instance that matches the filter; or Error. * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Array} model First model instance that matches the filter or null if none found.
*/ */
PersistedModel.findOne = function findOne(params, cb) { PersistedModel.findOne = function findOne(params, cb) {
@ -199,14 +212,14 @@ PersistedModel.findOne = function findOne(params, cb) {
/** /**
* Destroy all model instances that match the optional `where` specification. * Destroy all model instances that match the optional `where` specification.
* *
* @options {Object} [where] Optional where filter JSON object; see below. * @param {Object} [where] Optional where filter, like:
* @property {Object} where Where clause, like
* ``` * ```
* { key: val, key2: {gt: 'val2'}, ...} * { key: val, key2: {gt: 'val2'}, ...}
* ``` * ```
* <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter). * <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
* *
* @param {Function} [cb] - callback called with `(err)`. * @callback {Function} callback Optional callback function called with `(err)` argument.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
*/ */
PersistedModel.destroyAll = function destroyAll(where, cb) { PersistedModel.destroyAll = function destroyAll(where, cb) {
@ -224,7 +237,7 @@ PersistedModel.remove = PersistedModel.destroyAll;
PersistedModel.deleteAll = PersistedModel.destroyAll; PersistedModel.deleteAll = PersistedModel.destroyAll;
/** /**
* Update multiple instances that match the where clause * Update multiple instances that match the where clause.
* *
* Example: * Example:
* *
@ -234,14 +247,17 @@ PersistedModel.deleteAll = PersistedModel.destroyAll;
* }); * });
* ``` * ```
* *
* @options {Object} [where] Optional where filter JSON object; see below. * @param {Object} [where] Optional `where` filter, like
* @property {Object} where Where clause, like
* ``` * ```
* { key: val, key2: {gt: 'val2'}, ...} * { key: val, key2: {gt: 'val2'}, ...}
* ``` * ```
* <br/>see [Where filter](http://docs.strongloop.com/display/public/LB/Where+filter). * <br/>see [Where filter](http://docs.strongloop.com/display/public/LB/Where+filter).
* @param {Object} data Changes to be made * @param {Object} data Object containing data to replace matching instances, if any.
* @param {Function} cb Callback function called with (err, count). *
* @callback {Function} callback Callback function called with `(err, count)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Number} count Number of instances updated.
*
*/ */
PersistedModel.updateAll = function updateAll(where, data, cb) { PersistedModel.updateAll = function updateAll(where, data, cb) {
throwNotAttached(this.modelName, 'updateAll'); throwNotAttached(this.modelName, 'updateAll');
@ -255,7 +271,8 @@ PersistedModel.update = PersistedModel.updateAll;
/** /**
* Destroy model instance with the specified ID. * Destroy model instance with the specified ID.
* @param {*} id The ID value of model instance to delete. * @param {*} id The ID value of model instance to delete.
* @param {Function} cb Callback function called with (err). * @callback {Function} callback Callback function called with `(err)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
*/ */
PersistedModel.destroyById = function deleteById(id, cb) { PersistedModel.destroyById = function deleteById(id, cb) {
throwNotAttached(this.modelName, 'deleteById'); throwNotAttached(this.modelName, 'deleteById');
@ -273,12 +290,14 @@ PersistedModel.deleteById = PersistedModel.destroyById;
/** /**
* Return the number of records that match the optional "where" filter. * Return the number of records that match the optional "where" filter.
* @options {Object} [where] Optional where filter JSON object; See [Where filter](http://docs.strongloop.com/display/LB/Where+filter). * @parame {Object} [where] Optional where filter, like
* @property {Object} where Where clause, like
* ``` * ```
* { key: val, key2: {gt: 'val2'}, ...} * { key: val, key2: {gt: 'val2'}, ...}
* ``` * ```
* @param {Function} cb Callback function called with (err, count). * <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
* @callback {Function} callback Callback function called with `(err, count)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Number} count Number of instances updated.
*/ */
PersistedModel.count = function(where, cb) { PersistedModel.count = function(where, cb) {
@ -286,13 +305,15 @@ PersistedModel.count = function(where, cb) {
}; };
/** /**
* Save model instance. If the instance doesn't have an ID, then the [create](#persistedmodelcreatedata-cb) method is called instead. * Save model instance. If the instance doesn't have an ID, then calls [create](#persistedmodelcreatedata-cb) instead.
* Triggers: validate, save, update, or create. * Triggers: validate, save, update, or create.
* @options {Object} [options] See below. * @options {Object} [options] See below.
* @property {Boolean} validate Perform validation before saving. Default is true. * @property {Boolean} validate Perform validation before saving. Default is true.
* @property {Boolean} throws Controls If true, throw a validation error; WARNING: This can crash Node. * @property {Boolean} throws If true, throw a validation error; WARNING: This can crash Node.
* If false, report the error via callback. Default is false. * If false, report the error via callback. Default is false.
* @param {Function} [callback] Callback function called with (err, obj). * @callback {Function} callback Optional callback function called with `(err, obj)` arguments.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Object} instance Model instance saved or created.
*/ */
PersistedModel.prototype.save = function(options, callback) { PersistedModel.prototype.save = function(options, callback) {
@ -394,9 +415,11 @@ PersistedModel.prototype.destroy._delegate = true;
* Update a single attribute. * Update a single attribute.
* Equivalent to `updateAttributes({name: 'value'}, cb)` * Equivalent to `updateAttributes({name: 'value'}, cb)`
* *
* @param {String} name Name of property * @param {String} name Name of property.
* @param {Mixed} value Value of property * @param {Mixed} value Value of property.
* @param {Function} callback Callback function called with (err, instance). * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Object} instance Updated instance.
*/ */
PersistedModel.prototype.updateAttribute = function updateAttribute(name, value, callback) { PersistedModel.prototype.updateAttribute = function updateAttribute(name, value, callback) {
@ -406,9 +429,11 @@ PersistedModel.prototype.updateAttribute = function updateAttribute(name, value,
/** /**
* Update set of attributes. Performs validation before updating. * Update set of attributes. Performs validation before updating.
* *
* Trigger: `validation`, `save` and `update` hooks * Triggers: `validation`, `save` and `update` hooks
* @param {Object} data Dta to update. * @param {Object} data Dta to update.
* @param {Function} callback Callback function called with (err, instance). * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Object} instance Updated instance.
*/ */
PersistedModel.prototype.updateAttributes = function updateAttributes(data, cb) { PersistedModel.prototype.updateAttributes = function updateAttributes(data, cb) {
@ -417,7 +442,9 @@ PersistedModel.prototype.updateAttributes = function updateAttributes(data, cb)
/** /**
* Reload object from persistence. Requires `id` member of `object` to be able to call `find`. * Reload object from persistence. Requires `id` member of `object` to be able to call `find`.
* @param {Function} callback Callback function called with (err, instance) arguments. * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Object} instance Model instance.
*/ */
PersistedModel.prototype.reload = function reload(callback) { PersistedModel.prototype.reload = function reload(callback) {
@ -425,8 +452,8 @@ PersistedModel.prototype.reload = function reload(callback) {
}; };
/** /**
* Set the correct `id` property for the `PersistedModel`. If a `Connector` defines * Set the correct `id` property for the `PersistedModel`. Uses the `setId` method if the model is attached to
* a `setId` method it will be used. Otherwise the default lookup is used. * connector that defines it. Otherwise, uses the default lookup.
* Override this method to handle complex IDs. * Override this method to handle complex IDs.
* *
* @param {*} val The `id` value. Will be converted to the type that the `id` property specifies. * @param {*} val The `id` value. Will be converted to the type that the `id` property specifies.
@ -450,7 +477,7 @@ PersistedModel.prototype.getId = function() {
}; };
/** /**
* Get the id property name of the constructor. * Get the `id` property name of the constructor.
* *
* @returns {String} The `id` property name * @returns {String} The `id` property name
*/ */
@ -460,7 +487,7 @@ PersistedModel.prototype.getIdName = function() {
}; };
/** /**
* Get the id property name of the constructor. * Get the `id` property name of the constructor.
* *
* @returns {String} The `id` property name * @returns {String} The `id` property name
*/ */
@ -683,11 +710,13 @@ PersistedModel.setupRemoting = function() {
/** /**
* Get a set of deltas and conflicts since the given checkpoint. * Get a set of deltas and conflicts since the given checkpoint.
* *
* See `Change.diff()` for details. * See [Change.diff()](#change-diff) for details.
* *
* @param {Number} since Find deltas since this checkpoint * @param {Number} since Find deltas since this checkpoint.
* @param {Array} remoteChanges An array of change objects * @param {Array} remoteChanges An array of change objects.
* @param {Function} callback * @callback {Function} callback Callback function called with `(err, result)` arguments. Required.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Object} result Object with `deltas` and `conflicts` properties; see [Change.diff()](#change-diff) for details.
*/ */
PersistedModel.diff = function(since, remoteChanges, callback) { PersistedModel.diff = function(since, remoteChanges, callback) {
@ -696,15 +725,13 @@ PersistedModel.diff = function(since, remoteChanges, callback) {
}; };
/** /**
* Get the changes to a model since a given checkpoint. Provide a filter object * Get the changes to a model since the specified checkpoint. Provide a filter object
* to reduce the number of results returned. * to reduce the number of results returned.
* @param {Number} since Only return changes since this checkpoint * @param {Number} since Return only changes since this checkpoint.
* @param {Object} filter Only include changes that match this filter * @param {Object} filter Include only changes that match this filter, the same as for [#persistedmodel-find](find()).
* (same as `Model.find(filter, ...)`) * @callback {Function} callback Callback function called with `(err, changes)` arguments. Required.
* @callback {Function} callback * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Error} err * @param {Array} changes An array of [Change](#change) objects.
* @param {Array} changes An array of `Change` objects
* @end
*/ */
PersistedModel.changes = function(since, filter, callback) { PersistedModel.changes = function(since, filter, callback) {
@ -769,12 +796,11 @@ PersistedModel.checkpoint = function(cb) {
}; };
/** /**
* Get the current checkpoint id. * Get the current checkpoint ID.
* *
* @callback {Function} callback * @callback {Function} callback Callback function called with `(err, currentCheckpointId)` arguments. Required.
* @param {Error} err * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Number} currentCheckpointId * @param {Number} currentCheckpointId Current checkpoint ID.
* @end
*/ */
PersistedModel.currentCheckpoint = function(cb) { PersistedModel.currentCheckpoint = function(cb) {
@ -785,14 +811,13 @@ PersistedModel.currentCheckpoint = function(cb) {
/** /**
* Replicate changes since the given checkpoint to the given target model. * Replicate changes since the given checkpoint to the given target model.
* *
* @param {Number} [since] Since this checkpoint * @param {Number} [since] Since this checkpoint
* @param {Model} targetModel Target this model class * @param {Model} targetModel Target this model class
* @param {Object} [options] * @param {Object} [options]
* @param {Object} [options.filter] Replicate models that match this filter * @param {Object} [options.filter] Replicate models that match this filter
* @callback {Function} [callback] * @callback {Function} [callback] Callback function called with `(err, conflicts)` arguments.
* @param {Error} err * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Conflict[]} conflicts A list of changes that could not be replicated * @param {Conflict[]} conflicts A list of changes that could not be replicated due to conflicts.
* due to conflicts.
*/ */
PersistedModel.replicate = function(since, targetModel, options, callback) { PersistedModel.replicate = function(since, targetModel, options, callback) {
@ -936,8 +961,8 @@ PersistedModel.createUpdates = function(deltas, cb) {
* *
* **Note: this is not atomic** * **Note: this is not atomic**
* *
* @param {Array} updates An updates list (usually from Model.createUpdates()) * @param {Array} updates An updates list, usually from [createUpdates()](#persistedmodel-createupdates).
* @param {Function} callback * @param {Function} callback Callback function.
*/ */
PersistedModel.bulkUpdate = function(updates, callback) { PersistedModel.bulkUpdate = function(updates, callback) {
@ -971,8 +996,7 @@ PersistedModel.bulkUpdate = function(updates, callback) {
/** /**
* Get the `Change` model. * Get the `Change` model.
* * Throws an error if the change model is not correctly setup.
* @throws {Error} Throws an error if the change model is not correctly setup.
* @return {Change} * @return {Change}
*/ */
@ -986,11 +1010,11 @@ PersistedModel.getChangeModel = function() {
}; };
/** /**
* Get the source identifier for this model / dataSource. * Get the source identifier for this model or dataSource.
* *
* @callback {Function} callback * @callback {Function} callback Callback function called with `(err, id)` arguments.
* @param {Error} err * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {String} sourceId * @param {String} sourceId Source identifier for the model or dataSource.
*/ */
PersistedModel.getSourceId = function(cb) { PersistedModel.getSourceId = function(cb) {
@ -1072,7 +1096,7 @@ PersistedModel.rectifyAllChanges = function(callback) {
* Handle a change error. Override this method in a subclassing model to customize * Handle a change error. Override this method in a subclassing model to customize
* change error handling. * change error handling.
* *
* @param {Error} err * @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
*/ */
PersistedModel.handleChangeError = function(err) { PersistedModel.handleChangeError = function(err) {
@ -1083,9 +1107,9 @@ PersistedModel.handleChangeError = function(err) {
}; };
/** /**
* Tell loopback that a change to the model with the given id has occurred. * Specify that a change to the model with the given ID has occurred.
* *
* @param {*} id The id of the model that has changed * @param {*} id The ID of the model that has changed.
* @callback {Function} callback * @callback {Function} callback
* @param {Error} err * @param {Error} err
*/ */