From 21547b9986b77e08180d32748cccdfa38dc1cd2c Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 2 Apr 2014 10:34:29 -0700 Subject: [PATCH 1/6] Add link to loopback.io --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 39b89125..46464037 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # LoopBack +For a quick introduction and overview, see http://loopback.io/. + ## Documentation [See the full documentation](http://docs.strongloop.com/display/DOC/LoopBack). From a265d6700737ef2bc6d7352bf7cc73cbad8d3886 Mon Sep 17 00:00:00 2001 From: crandmck Date: Wed, 2 Apr 2014 15:15:21 -0700 Subject: [PATCH 2/6] 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. From 006aca6b9c1e4917fc1dc8b8d8d555dc8d735f53 Mon Sep 17 00:00:00 2001 From: crandmck Date: Wed, 2 Apr 2014 15:46:39 -0700 Subject: [PATCH 3/6] Update and cleanup JSDoc --- lib/loopback.js | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/lib/loopback.js b/lib/loopback.js index 6a057a44..be705340 100644 --- a/lib/loopback.js +++ b/lib/loopback.js @@ -15,27 +15,29 @@ var express = require('express') , assert = require('assert'); /** - * `loopback` is the main entry for LoopBack core module. It provides static + * Main entry for 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, * - * * ```js * var loopback = require('loopback'); * var app = loopback(); * ``` + * + * @class loopback + * @header loopback */ var loopback = exports = module.exports = createApplication; /** - * Is this a browser environment? + * True if running in a browser environment; false otherwise. */ loopback.isBrowser = typeof window !== 'undefined'; /** - * Is this a server environment? + * True if running in a server environment; false otherwise. */ loopback.isServer = !loopback.isBrowser; @@ -116,11 +118,10 @@ loopback.errorHandler.title = 'Loopback'; /** * Create a data source with passing the provided options to the connector. * - * @param {String} name (optional) - * @param {Object} options - * - * - connector - an loopback connector - * - other values - see the specified `connector` docs + * @param {String} name Optional name. + * @options {Object} Data Source options + * @property {Object} connector LoopBack connector. + * @property {*} Other properties See the relevant connector documentation. */ loopback.createDataSource = function (name, options) { @@ -141,7 +142,7 @@ loopback.createDataSource = function (name, options) { /** * Create a named vanilla JavaScript class constructor with an attached set of properties and options. * - * @param {String} name - must be unique + * @param {String} name Unique name. * @param {Object} properties * @param {Object} options (optional) */ @@ -223,7 +224,7 @@ loopback.memory = function (name) { /** * Look up a model class by name from all models created by loopback.createModel() * @param {String} modelName The model name - * @return {Model} The model class + * @returns {Model} The model class */ loopback.getModel = function(modelName) { return loopback.Model.modelBuilder.models[modelName]; @@ -233,7 +234,7 @@ loopback.getModel = function(modelName) { * Look up a model class by the base model class. The method can be used by LoopBack * to find configured models in models.json over the base model. * @param {Model} The base model class - * @return {Model} The subclass if found or the base class + * @returns {Model} The subclass if found or the base class */ loopback.getModelByType = function(modelType) { assert(typeof modelType === 'function', 'The model type must be a constructor'); @@ -250,7 +251,7 @@ loopback.getModelByType = function(modelType) { * Set the default `dataSource` for a given `type`. * @param {String} type The datasource type * @param {Object|DataSource} dataSource The data source settings or instance - * @return {DataSource} The data source instance + * @returns {DataSource} The data source instance */ loopback.setDefaultDataSourceForType = function(type, dataSource) { @@ -267,7 +268,7 @@ loopback.setDefaultDataSourceForType = function(type, dataSource) { /** * Get the default `dataSource` for a given `type`. * @param {String} type The datasource type - * @return {DataSource} The data source instance + * @returns {DataSource} The data source instance */ loopback.getDefaultDataSourceForType = function(type) { From 4c246c7f2c84f835fe8f0a631ffde468c4da430f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Thu, 3 Apr 2014 10:39:42 +0200 Subject: [PATCH 4/6] Describe the "id" parameter of model's sharedCtor Extend remoting metadata to describe the "id" parameter accepted by the sharedCtor of all models. --- lib/models/model.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/models/model.js b/lib/models/model.js index 7d52c3b4..bb59b129 100644 --- a/lib/models/model.js +++ b/lib/models/model.js @@ -100,8 +100,9 @@ Model.setup = function () { }; // Map the prototype method to /:id with data in the body + var idDesc = ModelCtor.modelName + ' id'; ModelCtor.sharedCtor.accepts = [ - {arg: 'id', type: 'any', http: {source: 'path'}} + {arg: 'id', type: 'any', http: {source: 'path'}, description: idDesc} // {arg: 'instance', type: 'object', http: {source: 'body'}} ]; From dff182ed2710a4393fec98d1cb50b15720e84aa5 Mon Sep 17 00:00:00 2001 From: crandmck Date: Thu, 3 Apr 2014 11:29:00 -0700 Subject: [PATCH 5/6] Clean up JSDoc comments. Remove doc for deprecated installMiddleware function --- lib/application.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/application.js b/lib/application.js index 4242caa3..54d509ef 100644 --- a/lib/application.js +++ b/lib/application.js @@ -639,7 +639,8 @@ function clearHandlerCache(app) { app._handlers = undefined; } -/** +/*! + * This function is now deprecated. * Install all express middleware required by LoopBack. * * It is possible to inject your own middleware by listening on one of the From 3640b2e113ed71a64e286def067c753ae7140d91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Fri, 4 Apr 2014 16:41:25 +0200 Subject: [PATCH 6/6] v1.7.4 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 945145b8..b9bf2ad9 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ "Platform", "mBaaS" ], - "version": "1.7.3", + "version": "1.7.4", "scripts": { "test": "mocha -R spec" },