Fix API docs to add proper callback doc per #1041
This commit is contained in:
crandmck
parent
9816999864
commit
538e9f0c62
|
|
@ -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 {Function} cb Callback function with `cb(err, obj)` signature,
|
||||
* where `err` is error object and `obj` is null or Model instance.
|
||||
* @param {Object}|[{Object}] data Optional data argument. Can be either a single model instance or an array of instances.
|
||||
*
|
||||
* @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) {
|
||||
|
|
@ -91,8 +93,10 @@ PersistedModel.create = function(data, callback) {
|
|||
|
||||
/**
|
||||
* Update or insert a model instance
|
||||
* @param {Object} data The model instance data
|
||||
* @param {Function} [callback] The callback function
|
||||
* @param {Object} data The model instance data to insert.
|
||||
* @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) {
|
||||
|
|
@ -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.
|
||||
*
|
||||
* @param {Object} where Where clause, such as `{where: {test: 'me'}}`
|
||||
* <br/>see [Where filter](http://docs.strongloop.com/display/public/LB/Where+filter).
|
||||
* @param {Object} data Object to create.
|
||||
* @param {Function} cb Callback called with `cb(err, instance)` signature.
|
||||
* @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).
|
||||
* @param {Object} instance Model instance matching the `where` filter, if found.
|
||||
*/
|
||||
|
||||
PersistedModel.findOrCreate = function findOrCreate(query, data, callback) {
|
||||
|
|
@ -118,8 +125,11 @@ PersistedModel.findOrCreate._delegate = true;
|
|||
/**
|
||||
* Check whether a model instance exists in database.
|
||||
*
|
||||
* @param {id} id Identifier of object (primary key value)
|
||||
* @param {Function} cb Callback function called with `(err, exists: Bool)`
|
||||
* @param {id} id Identifier of object (primary key value).
|
||||
*
|
||||
* @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) {
|
||||
|
|
@ -129,8 +139,11 @@ PersistedModel.exists = function exists(id, cb) {
|
|||
/**
|
||||
* Find object by ID.
|
||||
*
|
||||
* @param {*} id - primary key value
|
||||
* @param {Function} cb Callback function called with `(err, instances)`. Required.
|
||||
* @param {*} id Primary key value
|
||||
* @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) {
|
||||
|
|
@ -158,10 +171,9 @@ PersistedModel.findById = function find(id, cb) {
|
|||
* ```
|
||||
* <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
|
||||
*
|
||||
* @param {Function} Callback function called with `(err, returned-instances)`.
|
||||
* @callback {Function} callback
|
||||
* @param {Error} err
|
||||
* @param {Array} models Model instances matching the filter
|
||||
* @callback {Function} callback Callback function called with `(err, returned-instances)` arguments. Required.
|
||||
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
|
||||
* @param {Array} models Model instances matching the filter, or null if none found.
|
||||
*/
|
||||
|
||||
PersistedModel.find = function find(params, cb) {
|
||||
|
|
@ -187,9 +199,10 @@ PersistedModel.find = function find(params, cb) {
|
|||
* { key: val, key2: {gt: 'val2'}, ...}
|
||||
* ```
|
||||
* <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
|
||||
*
|
||||
* @param {Function} Callback function called with `(err, returned-instance)`. Required.
|
||||
* @returns {Object} First model instance that matches the filter; or Error.
|
||||
*
|
||||
* @callback {Function} callback Callback function called with `(err, returned-instance)` arguments. Required.
|
||||
* @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) {
|
||||
|
|
@ -199,14 +212,14 @@ PersistedModel.findOne = function findOne(params, cb) {
|
|||
/**
|
||||
* Destroy all model instances that match the optional `where` specification.
|
||||
*
|
||||
* @options {Object} [where] Optional where filter JSON object; see below.
|
||||
* @property {Object} where Where clause, like
|
||||
* @param {Object} [where] Optional where filter, like:
|
||||
* ```
|
||||
* { key: val, key2: {gt: 'val2'}, ...}
|
||||
* ```
|
||||
* <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) {
|
||||
|
|
@ -224,7 +237,7 @@ PersistedModel.remove = PersistedModel.destroyAll;
|
|||
PersistedModel.deleteAll = PersistedModel.destroyAll;
|
||||
|
||||
/**
|
||||
* Update multiple instances that match the where clause
|
||||
* Update multiple instances that match the where clause.
|
||||
*
|
||||
* Example:
|
||||
*
|
||||
|
|
@ -234,14 +247,17 @@ PersistedModel.deleteAll = PersistedModel.destroyAll;
|
|||
* });
|
||||
* ```
|
||||
*
|
||||
* @options {Object} [where] Optional where filter JSON object; see below.
|
||||
* @property {Object} where Where clause, like
|
||||
* @param {Object} [where] Optional `where` filter, like
|
||||
* ```
|
||||
* { key: val, key2: {gt: 'val2'}, ...}
|
||||
* ```
|
||||
* <br/>see [Where filter](http://docs.strongloop.com/display/public/LB/Where+filter).
|
||||
* @param {Object} data Changes to be made
|
||||
* @param {Function} cb Callback function called with (err, count).
|
||||
* @param {Object} data Object containing data to replace matching instances, if any.
|
||||
*
|
||||
* @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) {
|
||||
throwNotAttached(this.modelName, 'updateAll');
|
||||
|
|
@ -255,7 +271,8 @@ PersistedModel.update = PersistedModel.updateAll;
|
|||
/**
|
||||
* Destroy model instance with the specified ID.
|
||||
* @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) {
|
||||
throwNotAttached(this.modelName, 'deleteById');
|
||||
|
|
@ -273,12 +290,14 @@ PersistedModel.deleteById = PersistedModel.destroyById;
|
|||
|
||||
/**
|
||||
* 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).
|
||||
* @property {Object} where Where clause, like
|
||||
* @parame {Object} [where] Optional where filter, like
|
||||
* ```
|
||||
* { 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) {
|
||||
|
|
@ -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.
|
||||
* @options {Object} [options] See below.
|
||||
* @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.
|
||||
* @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) {
|
||||
|
|
@ -394,9 +415,11 @@ PersistedModel.prototype.destroy._delegate = true;
|
|||
* Update a single attribute.
|
||||
* Equivalent to `updateAttributes({name: 'value'}, cb)`
|
||||
*
|
||||
* @param {String} name Name of property
|
||||
* @param {Mixed} value Value of property
|
||||
* @param {Function} callback Callback function called with (err, instance).
|
||||
* @param {String} name Name of property.
|
||||
* @param {Mixed} value Value of property.
|
||||
* @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) {
|
||||
|
|
@ -406,9 +429,11 @@ PersistedModel.prototype.updateAttribute = function updateAttribute(name, value,
|
|||
/**
|
||||
* 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 {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) {
|
||||
|
|
@ -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`.
|
||||
* @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) {
|
||||
|
|
@ -425,8 +452,8 @@ PersistedModel.prototype.reload = function reload(callback) {
|
|||
};
|
||||
|
||||
/**
|
||||
* Set the correct `id` property for the `PersistedModel`. If a `Connector` defines
|
||||
* a `setId` method it will be used. Otherwise the default lookup is used.
|
||||
* Set the correct `id` property for the `PersistedModel`. Uses the `setId` method if the model is attached to
|
||||
* connector that defines it. Otherwise, uses the default lookup.
|
||||
* Override this method to handle complex IDs.
|
||||
*
|
||||
* @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
|
||||
*/
|
||||
|
|
@ -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
|
||||
*/
|
||||
|
|
@ -683,11 +710,13 @@ PersistedModel.setupRemoting = function() {
|
|||
/**
|
||||
* 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 {Array} remoteChanges An array of change objects
|
||||
* @param {Function} callback
|
||||
* @param {Number} since Find deltas since this checkpoint.
|
||||
* @param {Array} remoteChanges An array of change objects.
|
||||
* @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) {
|
||||
|
|
@ -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.
|
||||
* @param {Number} since Only return changes since this checkpoint
|
||||
* @param {Object} filter Only include changes that match this filter
|
||||
* (same as `Model.find(filter, ...)`)
|
||||
* @callback {Function} callback
|
||||
* @param {Error} err
|
||||
* @param {Array} changes An array of `Change` objects
|
||||
* @end
|
||||
* @param {Number} since Return only changes since this checkpoint.
|
||||
* @param {Object} filter Include only changes that match this filter, the same as for [#persistedmodel-find](find()).
|
||||
* @callback {Function} callback Callback function called with `(err, changes)` arguments. Required.
|
||||
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
|
||||
* @param {Array} changes An array of [Change](#change) objects.
|
||||
*/
|
||||
|
||||
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
|
||||
* @param {Error} err
|
||||
* @param {Number} currentCheckpointId
|
||||
* @end
|
||||
* @callback {Function} callback Callback function called with `(err, currentCheckpointId)` arguments. Required.
|
||||
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
|
||||
* @param {Number} currentCheckpointId Current checkpoint ID.
|
||||
*/
|
||||
|
||||
PersistedModel.currentCheckpoint = function(cb) {
|
||||
|
|
@ -785,14 +811,13 @@ PersistedModel.currentCheckpoint = function(cb) {
|
|||
/**
|
||||
* 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 {Object} [options]
|
||||
* @param {Object} [options.filter] Replicate models that match this filter
|
||||
* @callback {Function} [callback]
|
||||
* @param {Error} err
|
||||
* @param {Conflict[]} conflicts A list of changes that could not be replicated
|
||||
* due to conflicts.
|
||||
* @callback {Function} [callback] Callback function called with `(err, conflicts)` arguments.
|
||||
* @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 due to conflicts.
|
||||
*/
|
||||
|
||||
PersistedModel.replicate = function(since, targetModel, options, callback) {
|
||||
|
|
@ -936,8 +961,8 @@ PersistedModel.createUpdates = function(deltas, cb) {
|
|||
*
|
||||
* **Note: this is not atomic**
|
||||
*
|
||||
* @param {Array} updates An updates list (usually from Model.createUpdates())
|
||||
* @param {Function} callback
|
||||
* @param {Array} updates An updates list, usually from [createUpdates()](#persistedmodel-createupdates).
|
||||
* @param {Function} callback Callback function.
|
||||
*/
|
||||
|
||||
PersistedModel.bulkUpdate = function(updates, callback) {
|
||||
|
|
@ -971,8 +996,7 @@ PersistedModel.bulkUpdate = function(updates, callback) {
|
|||
|
||||
/**
|
||||
* Get the `Change` model.
|
||||
*
|
||||
* @throws {Error} Throws an error if the change model is not correctly setup.
|
||||
* Throws an error if the change model is not correctly setup.
|
||||
* @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
|
||||
* @param {Error} err
|
||||
* @param {String} sourceId
|
||||
* @callback {Function} callback Callback function called with `(err, id)` arguments.
|
||||
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
|
||||
* @param {String} sourceId Source identifier for the model or dataSource.
|
||||
*/
|
||||
|
||||
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
|
||||
* 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) {
|
||||
|
|
@ -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
|
||||
* @param {Error} err
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue