Clean up jsdoc comments

Add class properties, expose some methods that should have
been documented, etc.

common/models/application.js

@@ -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) {

common/models/change.js

@@ -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

common/models/email.js

@@ -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.

common/models/role.js

@@ -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 {*} modelId The model ID
-   * @param {*) userId The user id
+   * @param {*} userId The user ID
- * @param {Function} callback
+   * @param {Function} callback Callback function
    */
   Role.isOwner = function isOwner(modelClass, modelId, userId, callback) {
     assert(modelClass, 'Model class is required');

common/models/user.js

@@ -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) {

docs.json

@@ -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",

lib/application.js

@@ -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
+ * supports Express middleware. See
- * [Express / Connect middleware](http://expressjs.com/api.html#middleware). See
+ * [Express documentation](http://expressjs.com/) for details.
- * [Express documentation](http://expressjs.com/api.html) 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
+ * Example - Attach an existing model:
- * // 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
+ * @property {String|DataSource} dataSource The `DataSource` to which to attach the model.
- * attach the model.
+ * @property {Boolean} [public] Whether the model should be exposed via REST API.
- * @property {Boolean} [public] whether the model should be exposed via REST API
+ * @property {Object} [relations] Relations to add/update.
- * @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.

lib/loopback.js

@@ -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.
  */
 

lib/model.js

@@ -86,10 +86,10 @@ var stringUtils = require('underscore.string');
  * });
  * ```
  * 
- * @class
  * @param {Object} data
- * @property {String} modelName The name of the model
+ * @property {String} modelName The name of the model.   Static property.
- * @property {DataSource} dataSource
+ * @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 {SharedMethod} sharedMethod The method in question.
- * @param {Object} ctx The remote invocation context
+ * @param {Object} ctx The remote invocation context.
- * @callback {Function} callback The callback function
+ * @callback {Function} callback The callback function.
- * @param {String|Error} err The error object
+ * @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();

lib/persisted-model.js

@@ -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 {Object} data Optional data object.
- * @param callback(err, obj)
+ * @param {Function} cb Callback function with `cb(err, obj)` signature,
- * callback called with arguments:
+ *  where `err` is error object and `obj` is null or Model instance.
- *
- *   - err (null or Error)
- *   - instance (null or Model)
  */
 
 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,
+ * Find one record, same as `find`, but limited to one object.  Returns an object, not collection.
- * if not found, create using data provided as second argument
+ * If not found, create the object using data provided as second argument.
  *
- * @param {Object} query - search conditions: {where: {test: 'me'}}.
+ * @param {Object} query Search conditions: {where: {test: 'me'}}.
- * @param {Object} data - object to create.
+ * @param {Object} data Object to create.
- * @param {Function} cb - callback called with (err, instance)
+ * @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 {id} id Identifier of object (primary key value)
- * @param {Function} cb - callback called with (err, exists: Bool)
+ * @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
+ * Find all model instances that match `filter` specification.
- * make sure you have marked as `index: true` fields for filter or sort
+ * 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'}}`
+ * @param {Function} Callback function called with `(err, returned-instances)`.
- * - include: String, Object or Array. See PersistedModel.include documentation.
+ * @returns {Object} Array of model instances that match the filter; or Error.
- * - order: String
- * - limit: Number
- * - skip: Number
- *
- * @param {Function} callback (required) called with arguments:
- *
- * - err (null or Error)
- * - Array of instances
  */
 
 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'}}
+ * @options {Object} [filter] Optional Filter JSON object; see below.
- * @param {Function} cb - callback called with (err, instance)
+ * @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
+ * Destroy all model instances that match the optional `filter` specification.
- * @param {Object} [where] An object that defines the criteria
+ *
- * @param {Function} [cb] - callback called with (err)
+ * @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');
 };
 
-/**
+PersistedModel.update = PersistedModel.updateAll;
- * Destroy a record by id
- * @param {*} id The id value
- * @param {Function} cb - callback called with (err)
- */
 
-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
+ * Alias for destroyById.
- *
+ */
- * @param {Object} where - search conditions (optional)
+PersistedModel.removeById = PersistedModel.destroyById
- * @param {Function} cb - callback, called with (err, count)
+
+/**
+ * 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.
+ * Save model instance. If the instance doesn't have an ID, then the [create](#persistedmodelcreatedata-cb) method is called instead.
- * Triggers: validate, save, update | create
+ * Triggers: validate, save, update, or create.
- * @param options {validate: true, throws: false} [optional]
+ * @options {Object} [options] See below.
- * @param callback(err, obj)
+ * @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
+ * Deletes the model from persistence.
- *
+ * Triggers `destroy` hook (async) before and after destroying object.
- * @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 {String} name - name of property
+ * @param {Function} callback Callback function called with (err, instance).
- * @param {Mixed} value - value of property
- * @param {Function} callback - callback 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 Dta to update.
- * @trigger `validation`, `save` and `update` hooks
+ * @param {Function} callback Callback function called with (err, instance).
- * @param {Object} data - data to update
- * @param {Function} callback - callback 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
+ * 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.
- * @requires `id` member of `object` to be able to call `find`
- * @param {Function} callback - 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
+ * a `setId` method it will be used. Otherwise the default lookup is used.
- * should override this method to handle complex ids.
+ * Override this method to handle complex IDs.
  *
- * @param {*} val The `id` value. Will be converted to the type the id property
+ * @param {*} val The `id` value. Will be converted to the type that the `id` property specifies.
- * specifies.
  */
 
 PersistedModel.prototype.setId = function(val) {

lib/registry.js

@@ -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
+ * @param {String} type The datasource type.
- * @returns {DataSource} The data source instance
+ * @returns {DataSource} The data source instance.
- * @header loopback.getDefaultDataSourceForType()
+ * @header loopback.getDefaultDataSourceForType(type)
  */
 
 registry.getDefaultDataSourceForType = function(type) {