Update and cleanup JSDoc

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 {String} name Optional name.
- * @param {Object} options
+ * @options {Object} Data Source options
- * 
+ * @property {Object} connector LoopBack connector.
- *  - connector - an loopback connector
+ * @property {*} Other properties See the relevant connector documentation. 
- *  - other values - see the specified `connector` docs 
  */
 
 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) {