From a265d6700737ef2bc6d7352bf7cc73cbad8d3886 Mon Sep 17 00:00:00 2001 From: crandmck Date: Wed, 2 Apr 2014 15:15:21 -0700 Subject: [PATCH] Cleanup and update of jsdoc --- lib/application.js | 91 ++++++++++++++++++++-------------------------- 1 file changed, 40 insertions(+), 51 deletions(-) diff --git a/lib/application.js b/lib/application.js index f7090d81..4242caa3 100644 --- a/lib/application.js +++ b/lib/application.js @@ -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. * * * **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.