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