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

Cleanup and update of jsdoc

This commit is contained in:
crandmck 2014-04-02 15:15:21 -07:00
parent 21547b9986
commit a265d67007
1 changed files with 40 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
lib/application.js
View File

@ -48,8 +48,7 @@ var app = exports = module.exports = {};
/** /**
* Lazily load a set of [remote objects](http://apidocs.strongloop.com/strong-remoting/#remoteobjectsoptions). * Lazily load a set of [remote objects](http://apidocs.strongloop.com/strong-remoting/#remoteobjectsoptions).
* *
* **NOTE:** Calling `app.remotes()` multiple times will only ever return a * **NOTE:** Calling `app.remotes()` more than once returns only a single set of remote objects.
* single set of remote objects.
* @returns {RemoteObjects} * @returns {RemoteObjects}
*/ */
@ -88,13 +87,13 @@ app.disuse = function (route) {
* }); * });
* ``` * ```
* *
* @param {String} modelName The name of the model to define * @param {String} modelName The name of the model to define.
* @options {Object} config The model's configuration * @options {Object} config The model's configuration.
* @property {String|DataSource} dataSource The `DataSource` to attach the model to * @property {String|DataSource} dataSource The `DataSource` to which to attach the model.
* @property {Object} [options] an object containing `Model` options * @property {Object} [options] an object containing `Model` options.
* @property {ACL[]} [options.acls] an array of `ACL` definitions * @property {ACL[]} [options.acls] an array of `ACL` definitions.
* @property {String[]} [options.hidden] **experimental** an array of properties to hide when accessed remotely * @property {String[]} [options.hidden] **experimental** an array of properties to hide when accessed remotely.
* @property {Object} [properties] object defining the `Model` properties in [LoopBack Definition Language](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language) * @property {Object} [properties] object defining the `Model` properties in [LoopBack Definition Language](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language).
* @end * @end
* @returns {ModelConstructor} the model class * @returns {ModelConstructor} the model class
*/ */
@ -129,14 +128,11 @@ app.model = function (Model, config) {
} }
/** /**
* Get the models exported by the app. Only models defined using `app.model()` * Get the models exported by the app. Returns only models defined using `app.model()`
* will show up in this list.
* *
* There are two ways how to access models. * There are two ways to access models:
* *
* **1. A list of all models** * 1. Call `app.models()` to get a list of all models.
*
* Call `app.models()` to get a list of all models.
* *
* ```js * ```js
* var models = app.models(); * var models = app.models();
@ -146,12 +142,11 @@ app.model = function (Model, config) {
* }); * });
* ``` * ```
* *
* **2. By model name** * **2. Use `app.model` to access a model by name.
*
* `app.model` has properties for all defined models. * `app.model` has properties for all defined models.
* *
* In the following example the `Product` and `CustomerReceipt` models are * The following example illustrates accessing the `Product` and `CustomerReceipt` models
* accessed using the `models` object. * using the `models` object.
* *
* ```js * ```js
* var loopback = require('loopback'); * var loopback = require('loopback');
@ -178,7 +173,7 @@ app.model = function (Model, config) {
* var customerReceipt = app.models.customerReceipt; * var customerReceipt = app.models.customerReceipt;
* ``` * ```
* *
* @returns {Array} a list of model classes * @returns {Array} Array of model classes.
*/ */
app.models = function () { app.models = function () {
@ -200,6 +195,7 @@ app.dataSource = function (name, config) {
/** /**
* Get all remote objects. * Get all remote objects.
* @returns {Object} [Remote objects](http://apidocs.strongloop.com/strong-remoting/#remoteobjectsoptions).
*/ */
app.remoteObjects = function () { app.remoteObjects = function () {
@ -220,8 +216,7 @@ app.remoteObjects = function () {
/** /**
* Enable swagger REST API documentation. * Enable swagger REST API documentation.
* *
* > Note: This method is deprecated, use the extension * **Note**: This method is deprecated. Use [loopback-explorer](http://npmjs.org/package/loopback-explorer) instead.
* [loopback-explorer](http://npmjs.org/package/loopback-explorer) instead.
* *
* **Options** * **Options**
* *
@ -314,29 +309,30 @@ app.enableAuth = function() {
/** /**
* Initialize an application from an options object or a set of JSON and JavaScript files. * Initialize an application from an options object or a set of JSON and JavaScript files.
* *
* **What happens during an app _boot_?** * This function takes an optional argument that is either a string or an object.
* *
* 1. **DataSources** are created from an `options.dataSources` object or `datasources.json` in the current directory * If the argument is a string, then it sets the application root directory based on the string value. Then it:
* 2. **Models** are created from an `options.models` object or `models.json` in the current directory * 1. Creates DataSources from the `datasources.json` file in the application root directory.
* 3. Any JavaScript files in the `./models` directory are loaded with `require()`. * 2. Creates Models from the `models.json` file in the application root directory.
* 4. Any JavaScript files in the `./boot` directory are loaded with `require()`.
* *
* **Options** * If the argument is an object, then it looks for `model`, `dataSources`, and `appRootDir` properties of the object.
* * If the object has no `appRootDir` property then it sets the current working directory as the application root directory.
* - `appRootDir` - _optional_ - the directory to use when loading JSON and JavaScript files * Then it:
* - `models` - _optional_ - an object containing `Model` definitions * 1. Creates DataSources from the `options.dataSources` object.
* - `dataSources` - _optional_ - an object containing `DataSource` definitions * 2. Creates Models from the `options.models` object.
* *
* > **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple * In both cases, the function loads JavaScript files in the `/models` and `/boot` subdirectories of the application root directory with `require()`.
* > files may result *
* > in models being **undefined** due to race conditions. To avoid this when * **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple
* > using `app.boot()` * files may result in models being **undefined** due to race conditions.
* > make sure all models are passed as part of the `models` definition. * To avoid this when using `app.boot()` make sure all models are passed as part of the `models` definition.
*
* Throws an error if the config object is not valid or if boot fails.
* *
* <a name="model-definition"></a> * <a name="model-definition"></a>
* **Model Definitions** * **Model Definitions**
* *
* The following is an example of an object containing two `Model` definitions: "location" and "inventory". * The following is example JSON for two `Model` definitions: "dealership" and "location".
* *
* ```js * ```js
* { * {
@ -381,20 +377,13 @@ app.enableAuth = function() {
* } * }
* } * }
* ``` * ```
* * @options {String|Object} options Boot options; If String, this is the application root directory; if object, has below properties.
* **Model definition properties** * @property {String} appRootDir Directory to use when loading JSON and JavaScript files (optional). Defaults to the current directory (`process.cwd()`).
* * @property {Object} models Object containing `Model` definitions (optional).
* - `dataSource` - **required** - a string containing the name of the data source definition to attach the `Model` to * @property {Object} dataSources Object containing `DataSource` definitions (optional).
* - `options` - _optional_ - an object containing `Model` options * @end
* - `properties` _optional_ - an object defining the `Model` properties in [LoopBack Definition Language](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language)
*
* **DataSource definition properties**
*
* - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
* *
* @header app.boot([options]) * @header app.boot([options])
* @throws {Error} If config is not valid
* @throws {Error} If boot fails
*/ */
app.boot = function(options) { app.boot = function(options) {
@ -799,7 +788,7 @@ app.installMiddleware = function() {
* This way the port param contains always the real port number, even when * This way the port param contains always the real port number, even when
* listen was called with port number 0. * listen was called with port number 0.
* *
* @param {Function=} cb If specified, the callback will be added as a listener * @param {Function} cb If specified, the callback is added as a listener
* for the server's "listening" event. * for the server's "listening" event.
* @returns {http.Server} A node `http.Server` with this application configured * @returns {http.Server} A node `http.Server` with this application configured
* as the request handler. * as the request handler.