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).
*
* **NOTE:** Calling `app.remotes()` multiple times will only ever return a
* single set of remote objects.
* **NOTE:** Calling `app.remotes()` more than once returns only a single set of remote objects.
* @returns {RemoteObjects}
*/
@ -88,13 +87,13 @@ app.disuse = function (route) {
* });
* ```
*
* @param {String} modelName The name of the model to define
* @options {Object} config The model's configuration
* @property {String|DataSource} dataSource The `DataSource` to attach the model to
* @property {Object} [options] an object containing `Model` options
* @property {ACL[]} [options.acls] an array of `ACL` definitions
* @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)
* @param {String} modelName The name of the model to define.
* @options {Object} config The model's configuration.
* @property {String|DataSource} dataSource The `DataSource` to which to attach the model.
* @property {Object} [options] an object containing `Model` options.
* @property {ACL[]} [options.acls] an array of `ACL` definitions.
* @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).
* @end
* @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()`
* will show up in this list.
* Get the models exported by the app. Returns only models defined using `app.model()`
*
* There are two ways how to access models.
* There are two ways to access models:
*
* **1. A list of all models**
*
* Call `app.models()` to get a list of all models.
* 1. Call `app.models()` to get a list of all models.
*
* ```js
* 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.
*
* In the following example the `Product` and `CustomerReceipt` models are
* accessed using the `models` object.
* The following example illustrates accessing the `Product` and `CustomerReceipt` models
* using the `models` object.
*
* ```js
* var loopback = require('loopback');
@ -178,7 +173,7 @@ app.model = function (Model, config) {
* var customerReceipt = app.models.customerReceipt;
* ```
*
* @returns {Array} a list of model classes
* @returns {Array} Array of model classes.
*/
app.models = function () {
@ -200,6 +195,7 @@ app.dataSource = function (name, config) {
/**
* Get all remote objects.
* @returns {Object} [Remote objects](http://apidocs.strongloop.com/strong-remoting/#remoteobjectsoptions).
*/
app.remoteObjects = function () {
@ -220,8 +216,7 @@ app.remoteObjects = function () {
/**
* Enable swagger REST API documentation.
*
* > Note: This method is deprecated, use the extension
* [loopback-explorer](http://npmjs.org/package/loopback-explorer) instead.
* **Note**: This method is deprecated. Use [loopback-explorer](http://npmjs.org/package/loopback-explorer) instead.
*
* **Options**
*
@ -314,29 +309,30 @@ app.enableAuth = function() {
/**
* 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
* 2. **Models** are created from an `options.models` object or `models.json` in the current directory
* 3. Any JavaScript files in the `./models` directory are loaded with `require()`.
* 4. Any JavaScript files in the `./boot` directory are loaded with `require()`.
* If the argument is a string, then it sets the application root directory based on the string value. Then it:
* 1. Creates DataSources from the `datasources.json` file in the application root directory.
* 2. Creates Models from the `models.json` file in the application root directory.
*
* **Options**
*
* - `appRootDir` - _optional_ - the directory to use when loading JSON and JavaScript files
* - `models` - _optional_ - an object containing `Model` definitions
* - `dataSources` - _optional_ - an object containing `DataSource` definitions
* 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.
* Then it:
* 1. Creates DataSources from the `options.dataSources` object.
* 2. Creates Models from the `options.models` object.
*
* > **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple
* > files may result
* > in models being **undefined** due to race conditions. To avoid this when
* > using `app.boot()`
* > make sure all models are passed as part of the `models` definition.
* In both cases, the function loads JavaScript files in the `/models` and `/boot` subdirectories of the application root directory with `require()`.
*
* **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple
* files may result in models being **undefined** due to race conditions.
* 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>
* **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
* {
@ -381,20 +377,13 @@ app.enableAuth = function() {
* }
* }
* ```
*
* **Model definition properties**
*
* - `dataSource` - **required** - a string containing the name of the data source definition to attach the `Model` to
* - `options` - _optional_ - an object containing `Model` options
* - `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)
* @options {String|Object} options Boot options; If String, this is the application root directory; if object, has below 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).
* @property {Object} dataSources Object containing `DataSource` definitions (optional).
* @end
*
* @header app.boot([options])
* @throws {Error} If config is not valid
* @throws {Error} If boot fails
*/
app.boot = function(options) {
@ -799,7 +788,7 @@ app.installMiddleware = function() {
* 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 will be 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.