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

Clean up jsdoc comments 

Add class properties, expose some methods that should have
been documented, etc.
This commit is contained in:
crandmck 2014-10-15 09:07:30 +02:00 committed by Miroslav Bajtoš
parent dcedfa03a1
commit 2f4a54d93c
11 changed files with 206 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
common/models/application.js
View File

@ -151,18 +151,17 @@ module.exports = function(Application) {
/**
* Authenticate the application id and key.
*
* `matched` parameter is one of:
* @param {Any} appId
* @param {String} key
* @callback {Function} callback
* @param {Error} err
* @param {String} matched The matching key; one of:
* - clientKey
* - javaScriptKey
* - restApiKey
* - windowsKey
* - masterKey
*
* @param {Any} appId
* @param {String} key
* @callback {Function} callback
* @param {Error} err
* @param {String} matched The matching key
*/
Application.authenticate = function(appId, key, cb) {
this.findById(appId, function(err, app) {

2
common/models/change.js
View File

@ -474,7 +474,7 @@ module.exports = function(Change) {
/**
* When two changes conflict a conflict is created.
*
* **Note: call `conflict.fetch()` to get the `target` and `source` models.
* **Note**: call `conflict.fetch()` to get the `target` and `source` models.
*
* @param {*} modelId
* @param {PersistedModel} SourceModel

1
common/models/email.js
View File

@ -1,4 +1,5 @@
/**
* Email model. Extends LoopBack base [Model](#model-new-model).
* @property {String} to Email addressee. Required.
* @property {String} from Email sender address. Required.
* @property {String} subject Email subject string. Required.

8
common/models/role.js
View File

@ -126,11 +126,11 @@ module.exports = function(Role) {
}
/**
* Check if a given userId is the owner the model instance
* Check if a given user ID is the owner the model instance.
* @param {Function} modelClass The model class
* @param {*} modelId The model id
* @param {*) userId The user id
* @param {Function} callback
* @param {*} modelId The model ID
* @param {*} userId The user ID
* @param {Function} callback Callback function
*/
Role.isOwner = function isOwner(modelClass, modelId, userId, callback) {
assert(modelClass, 'Model class is required');

15
common/models/user.js
View File

@ -15,7 +15,8 @@ var loopback = require('../../lib/loopback')
var debug = require('debug')('loopback:user');
/**
* Extends from the built in `loopback.Model` type.
* Built-in User model.
* Extends LoopBack [PersistedModel](#persistedmodel-new-persistedmodel).
*
* Default `User` ACLs.
*
@ -204,7 +205,17 @@ User.prototype.hasPassword = function(plain, fn) {
* user.verify(options, next);
* ```
*
* @param {Object} options
* @options {Object} options
* @property {String} type Must be 'email'.
* @property {String} to Email address to which verification email is sent.
* @property {String} from Sender email addresss, for example
* `'noreply@myapp.com'`.
* @property {String} subject Subject line text.
* @property {String} text Text of email.
* @property {String} template Name of template that displays verification
* page, for example, `'verify.ejs'.
* @property {String} redirect Page to which user will be redirected after
* they verify their email, for example `'/'` for root URI.
*/
User.prototype.verify = function(options, fn) {

1
docs.json
View File

@ -3,7 +3,6 @@
"content": [
"lib/application.js",
"lib/loopback.js",
"lib/runtime.js",
"lib/registry.js",
{ "title": "Base models", "depth": 2 },
"lib/model.js",

38
lib/application.js
View File

@ -16,9 +16,8 @@ var DataSource = require('loopback-datasource-juggler').DataSource
* The `App` object represents a Loopback application.
*
* The App object extends [Express](http://expressjs.com/api.html#express) and
* supports
* [Express / Connect middleware](http://expressjs.com/api.html#middleware). See
* [Express documentation](http://expressjs.com/api.html) for details.
* supports Express middleware. See
* [Express documentation](http://expressjs.com/) for details.
*
* ```js
* var loopback = require('loopback');
@ -83,30 +82,22 @@ app.disuse = function (route) {
* Attach a model to the app. The `Model` will be available on the
* `app.models` object.
*
* ```js
* // Attach an existing model
* Example - Attach an existing model:
```js
* var User = loopback.User;
* app.model(User);
*
* // Attach an existing model, alter some aspects of the model
*```
* Example - Attach an existing model, alter some aspects of the model:
* ```js
* var User = loopback.User;
* app.model(User, { dataSource: 'db' });
*
* // LoopBack 1.x way: create and attach a new model (deprecated)
* var Widget = app.model('Widget', {
* dataSource: 'db',
* properties: {
* name: 'string'
* }
* });
*```
*
* @param {Object|String} Model The model to attach.
* @options {Object} config The model's configuration.
* @property {String|DataSource} dataSource The `DataSource` to which to
* attach the model.
* @property {Boolean} [public] whether the model should be exposed via REST API
* @property {Object} [relations] relations to add/update
* @property {String|DataSource} dataSource The `DataSource` to which to attach the model.
* @property {Boolean} [public] Whether the model should be exposed via REST API.
* @property {Object} [relations] Relations to add/update.
* @end
* @returns {ModelConstructor} the model class
*/
@ -180,7 +171,7 @@ app.model = function (Model, config) {
* });
* ```
*
* **2. Use `app.model` to access a model by name.
* 2. Use `app.model` to access a model by name.
* `app.model` has properties for all defined models.
*
* The following example illustrates accessing the `Product` and `CustomerReceipt` models
@ -223,7 +214,6 @@ app.models = function () {
*
* @param {String} name The data source name
* @param {Object} config The data source config
* @param {DataSource} The registered data source
*/
app.dataSource = function (name, config) {
var ds = dataSourcesFromConfig(config, this.connectors);
@ -416,15 +406,15 @@ function clearHandlerCache(app) {
* When there are no parameters or there is only one callback parameter,
* the server will listen on `app.get('host')` and `app.get('port')`.
*
* For example, to listen on host/port configured in app config:
* ```js
* // listen on host/port configured in app config
* app.listen();
* ```
*
* Otherwise all arguments are forwarded to `http.Server.listen`.
*
* For example, to listen on the specified port and all hosts, and ignore app config.
* ```js
* // listen on the specified port and all hosts, ignore app config
* app.listen(80);
* ```
*
@ -433,7 +423,7 @@ function clearHandlerCache(app) {
* This way the port param contains always the real port number, even when
* listen was called with port number 0.
*
* @param {Function} cb If specified, the callback is added as a listener
* @param {Function} [cb] If specified, the callback is added as a listener
* for the server's "listening" event.
* @returns {http.Server} A node `http.Server` with this application configured
* as the request handler.

12
lib/loopback.js
View File

@ -11,28 +11,32 @@ var express = require('express')
, assert = require('assert');
/**
* Main entry for LoopBack core module. It provides static properties and
* LoopBack core module. It provides static properties and
* methods to create models and data sources. The module itself is a function
* that creates loopback `app`. For example,
* that creates loopback `app`. For example:
*
* ```js
* var loopback = require('loopback');
* var app = loopback();
* ```
*
* @property {String} version Version of LoopBack framework. Static read-only property.
* @property {String} mime
* @property {Boolean} isBrowser True if running in a browser environment; false otherwise. Static read-only property.
* @property {Boolean} isServer True if running in a server environment; false otherwise. Static read-only property.
* @class loopback
* @header loopback
*/
var loopback = exports = module.exports = createApplication;
/**
/*!
* Framework version.
*/
loopback.version = require('../package.json').version;
/**
/*!
* Expose mime.
*/

21
lib/model.js
View File

@ -86,10 +86,10 @@ var stringUtils = require('underscore.string');
* });
* ```
*
* @class
* @param {Object} data
* @property {String} modelName The name of the model
* @property {DataSource} dataSource
* @property {String} modelName The name of the model. Static property.
* @property {DataSource} dataSource Data source to which the model is connected, if any. Static property.
* @class
*/
var Model = module.exports = registry.modelBuilder.define('Model');
@ -256,14 +256,14 @@ Model._ACL = function getACL(ACL) {
};
/**
* Check if the given access token can invoke the method
* Check if the given access token can invoke the specified method.
*
* @param {AccessToken} token The access token
* @param {AccessToken} token The access token.
* @param {*} modelId The model ID.
* @param {SharedMethod} sharedMethod The method in question
* @param {Object} ctx The remote invocation context
* @callback {Function} callback The callback function
* @param {String|Error} err The error object
* @param {SharedMethod} sharedMethod The method in question.
* @param {Object} ctx The remote invocation context.
* @callback {Function} callback The callback function.
* @param {String|Error} err The error object.
* @param {Boolean} allowed True if the request is allowed; false otherwise.
*/
@ -362,7 +362,8 @@ Model.getApp = function(callback) {
/**
* Enable remote invocation for the method with the given name.
* See [Remote methods and hooks](http://docs.strongloop.com/display/LB/Remote+methods+and+hooks for more information.
* See [Defining remote methods](http://docs.strongloop.com/display/LB/Defining+remote+methods) for more information.
*
* Static method example:
* ```js
* Model.myMethod();

222
lib/persisted-model.js
View File

@ -21,8 +21,6 @@ var async = require('async');
* ```
*
* @class PersistedModel
* @param {Object} data
* @param {Number} data.id The default id property
*/
var PersistedModel = module.exports = Model.extend('PersistedModel');
@ -80,12 +78,9 @@ function convertNullToNotFoundError(ctx, cb) {
/**
* 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 Optional data object.
* @param {Function} cb Callback function with `cb(err, obj)` signature,
* where `err` is error object and `obj` is null or Model instance.
*/
PersistedModel.create = function (data, callback) {
@ -103,12 +98,12 @@ PersistedModel.upsert = PersistedModel.updateOrCreate = function upsert(data, ca
};
/**
* Find one record, same as `find`, limited by 1 and return object, not collection,
* if not found, create using data provided as second argument
* Find one record, 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} query - search conditions: {where: {test: 'me'}}.
* @param {Object} data - object to create.
* @param {Function} cb - callback called with (err, instance)
* @param {Object} query Search conditions: {where: {test: 'me'}}.
* @param {Object} data Object to create.
* @param {Function} cb Callback called with `cb(err, instance)` signature.
*/
PersistedModel.findOrCreate = function findOrCreate(query, data, callback) {
@ -118,10 +113,10 @@ PersistedModel.findOrCreate = function findOrCreate(query, data, callback) {
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 {Function} cb - callback called with (err, exists: Bool)
* @param {id} id Identifier of object (primary key value)
* @param {Function} cb Callback function called with (err, exists: Bool)
*/
PersistedModel.exists = function exists(id, cb) {
@ -129,10 +124,10 @@ PersistedModel.exists = function exists(id, cb) {
};
/**
* Find object by id
* Find object by ID.
*
* @param {*} id - primary key value
* @param {Function} cb - callback called with (err, instance)
* @param {Function} cb Callback function called with `(err, returned-instance)`. Required.
*/
PersistedModel.findById = function find(id, cb) {
@ -140,21 +135,28 @@ PersistedModel.findById = function find(id, cb) {
};
/**
* Find all instances of Model, matched by query
* make sure you have marked as `index: true` fields for filter or sort
* Find all model instances that match `filter` specification.
* See [Querying models](http://docs.strongloop.com/display/LB/Querying+models).
*
* @param {Object} params (optional)
* @options {Object} [filter] Optional Filter JSON 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
* ```
* { key: val, key2: {gt: 'val2'}, ...}
* ```
* <br/>See [Where filter](http://docs.strongloop.com/display/LB/Where+filter).
*
* - where: Object `{ key: val, key2: {gt: 'val2'}}`
* - include: String, Object or Array. See PersistedModel.include documentation.
* - order: String
* - limit: Number
* - skip: Number
*
* @param {Function} callback (required) called with arguments:
*
* - err (null or Error)
* - Array of instances
* @param {Function} Callback function called with `(err, returned-instances)`.
* @returns {Object} Array of model instances that match the filter; or Error.
*/
PersistedModel.find = function find(params, cb) {
@ -162,10 +164,29 @@ PersistedModel.find = function find(params, cb) {
};
/**
* Find one record, same as `all`, limited by 1 and return object, not collection
* Find one model instance that matches `filter` specification.
* Same as `find`, but limited to one result;
* Returns object, not collection.
*
* @param {Object} params - search conditions: {where: {test: 'me'}}
* @param {Function} cb - callback called with (err, instance)
* @options {Object} [filter] Optional Filter JSON 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
* ```
* { 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.
*/
PersistedModel.findOne = function findOne(params, cb) {
@ -173,17 +194,31 @@ PersistedModel.findOne = function findOne(params, cb) {
};
/**
* Destroy all matching records
* @param {Object} [where] An object that defines the criteria
* @param {Function} [cb] - callback called with (err)
* Destroy all model instances that match the optional `filter` specification.
*
* @options {Object} [where] Optional where filter JSON object; see below.
* @property {Object} where Where clause, like
* ```
* { key: val, key2: {gt: 'val2'}, ...}
* ```
*
* @param {Function} [cb] - callback called with `(err)`.
*/
PersistedModel.remove =
PersistedModel.deleteAll =
PersistedModel.destroyAll = function destroyAll(where, cb) {
throwNotAttached(this.modelName, 'destroyAll');
};
/**
* Alias for `destroyAll`
*/
PersistedModel.remove = PersistedModel.destroyAll;
/**
* Alias for `destroyAll`
*/
PersistedModel.deleteAll = PersistedModel.destroyAll;
/**
* Update multiple instances that match the where clause
*
@ -195,32 +230,47 @@ PersistedModel.destroyAll = function destroyAll(where, cb) {
* });
* ```
*
* @param {Object} [where] Search conditions (optional)
* @options {Object} [where] Optional where filter JSON object; see below.
* @property {Object} where Where clause, like
* ```
* { key: val, key2: {gt: 'val2'}, ...}
* ```
* @param {Object} data Changes to be made
* @param {Function} cb Callback, called with (err, count)
* @param {Function} cb Callback function called with (err, count).
*/
PersistedModel.update =
PersistedModel.updateAll = function updateAll(where, data, cb) {
throwNotAttached(this.modelName, 'updateAll');
};
/**
* Destroy a record by id
* @param {*} id The id value
* @param {Function} cb - callback called with (err)
*/
PersistedModel.update = PersistedModel.updateAll;
PersistedModel.removeById =
PersistedModel.deleteById =
/**
* 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).
*/
PersistedModel.destroyById = function deleteById(id, cb) {
throwNotAttached(this.modelName, 'deleteById');
};
/**
* Return count of matched records
*
* @param {Object} where - search conditions (optional)
* @param {Function} cb - callback, called with (err, count)
* Alias for destroyById.
*/
PersistedModel.removeById = PersistedModel.destroyById
/**
* Alias for destroyById.
*/
PersistedModel.deleteById = PersistedModel.destroyById;
/**
* Return the number of records that match the optional filter.
* @options {Object} [filter] Optional where filter JSON object; see below.
* @property {Object} where Where clause, like
* ```
* { key: val, key2: {gt: 'val2'}, ...}
* ```
* @param {Function} cb Callback function called with (err, count).
*/
PersistedModel.count = function (where, cb) {
@ -228,10 +278,12 @@ PersistedModel.count = function (where, cb) {
};
/**
* 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 model instance. If the instance doesn't have an ID, then the [create](#persistedmodelcreatedata-cb) method is called instead.
* Triggers: validate, save, update, or create.
* @options {Object} [options] See below.
* @property {Boolean} validate
* @property {Boolean} throws
* @param {Function} callback Callback function called with (err, obj).
*/
PersistedModel.prototype.save = function (options, callback) {
@ -298,7 +350,7 @@ PersistedModel.prototype.save = function (options, callback) {
/**
* Determine if the data model is new.
* @returns {Boolean}
* @returns {Boolean} Returns true if the data model is new; false otherwise.
*/
PersistedModel.prototype.isNewRecord = function () {
@ -306,27 +358,36 @@ PersistedModel.prototype.isNewRecord = function () {
};
/**
* Delete object from persistence
*
* @triggers `destroy` hook (async) before and after destroying object
* Deletes the model from persistence.
* Triggers `destroy` hook (async) before and after destroying object.
* @param {Function} callback Callback function.
*/
PersistedModel.prototype.remove =
PersistedModel.prototype.delete =
PersistedModel.prototype.destroy = function (cb) {
throwNotAttached(this.constructor.modelName, 'destroy');
};
/**
* Alias for destroy.
* @header PersistedModel.remove
*/
PersistedModel.prototype.remove = PersistedModel.prototype.destroy;
/**
* Alias for destroy.
* @header PersistedModel.delete
*/
PersistedModel.prototype.delete = PersistedModel.prototype.destroy;
PersistedModel.prototype.destroy._delegate = true;
/**
* Update single attribute
* Update a single attribute.
* Equivalent to `updateAttributes({name: 'value'}, cb)`
*
* equals to `updateAttributes({name: value}, cb)
*
* @param {String} name - name of property
* @param {Mixed} value - value of property
* @param {Function} callback - callback called with (err, instance)
* @param {String} name Name of property
* @param {Mixed} value Value of property
* @param {Function} callback Callback function called with (err, instance).
*/
PersistedModel.prototype.updateAttribute = function updateAttribute(name, value, callback) {
@ -334,13 +395,11 @@ PersistedModel.prototype.updateAttribute = function updateAttribute(name, value,
};
/**
* Update set of attributes
* Update set of attributes. Performs validation before updating.
*
* this method performs validation before updating
*
* @trigger `validation`, `save` and `update` hooks
* @param {Object} data - data to update
* @param {Function} callback - callback called with (err, instance)
* Trigger: `validation`, `save` and `update` hooks
* @param {Object} data Dta to update.
* @param {Function} callback Callback function called with (err, instance).
*/
PersistedModel.prototype.updateAttributes = function updateAttributes(data, cb) {
@ -348,10 +407,8 @@ 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 - called with (err, instance) arguments
* 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.
*/
PersistedModel.prototype.reload = function reload(callback) {
@ -360,11 +417,10 @@ 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. You
* should override this method to handle complex ids.
* a `setId` method it will be used. Otherwise the default lookup is used.
* Override this method to handle complex IDs.
*
* @param {*} val The `id` value. Will be converted to the type the id property
* specifies.
* @param {*} val The `id` value. Will be converted to the type that the `id` property specifies.
*/
PersistedModel.prototype.setId = function(val) {

12
lib/registry.js
View File

@ -283,7 +283,7 @@ registry.createDataSource = function (name, options) {
* @param {String} [name] The name of the data source.
* If not provided, the `'default'` is used.
*
* @header loopback.memory()
* @header loopback.memory([name])
*/
registry.memory = function (name) {
@ -303,9 +303,9 @@ registry.memory = function (name) {
/**
* Set the default `dataSource` for a given `type`.
* @param {String} type The datasource type
* @param {String} type The datasource type.
* @param {Object|DataSource} dataSource The data source settings or instance
* @returns {DataSource} The data source instance
* @returns {DataSource} The data source instance.
*
* @header loopback.setDefaultDataSourceForType(type, dataSource)
*/
@ -323,9 +323,9 @@ registry.setDefaultDataSourceForType = function(type, dataSource) {
/**
* Get the default `dataSource` for a given `type`.
* @param {String} type The datasource type
* @returns {DataSource} The data source instance
* @header loopback.getDefaultDataSourceForType()
* @param {String} type The datasource type.
* @returns {DataSource} The data source instance.
* @header loopback.getDefaultDataSourceForType(type)
*/
registry.getDefaultDataSourceForType = function(type) {