Initial JSDoc cleanup

lib/model-builder.js

@@ -28,18 +28,14 @@ var slice = Array.prototype.slice;
 
 /**
  * ModelBuilder - A builder to define data models.
- *
+ * 
+ * @property {Object} definitions Definitions of the models.
+ * @property {Object} models Model constructors
  * @class
  */
 function ModelBuilder() {
   // create blank models pool
-  /**
-   * @property {Object} models Model constructors
-   */
   this.models = {};
-  /**
-   * @property {Object} definitions Definitions of the models
-   */
   this.definitions = {};
 }
 
@@ -276,7 +272,26 @@ ModelBuilder.prototype.define = function defineClass(className, properties, sett
     dataSource.attach(this);
   };
 
-  // A function to extend the model
+  /** Extend the model with the specified model, properties, and other settings.
+   * For example, to extend an existing model, for example, a built-in model:
+   *
+   * ```js
+   * var Customer = User.extend('customer', {
+   *   accountId: String,
+   *   vip: Boolean
+   * });
+   * ```
+   *
+   * To extend the base model, essentially creating a new model:
+   * ```js
+   * var user = loopback.Model.extend('user', properties, options);
+   * ```
+   * 
+   * @param {String} className Name of the new model being defined.
+   * @options {Object} properties Properties to define for the model, added to properties of model being extended.
+   * @options {Object} settings Model settings, such as relations and acls.
+   *
+   */ 
   ModelClass.extend = function (className, subclassProperties, subclassSettings) {
     var properties = ModelClass.definition.properties;
     var settings = ModelClass.definition.settings;
@@ -433,17 +448,20 @@ ModelBuilder.prototype.defineProperty = function (model, propertyName, propertyD
 };
 
 /**
- * Extend existing model with bunch of properties
+ * Extend existing model with specified properties
  *
  * Example:
- * Instead of doing amending the content model with competition attributes like this:
+ * Instead of extending a model with attributes like this (for example):
  * 
  * ```js
- *     db.defineProperty('Content', 'competitionType', { type: String });
- *     db.defineProperty('Content', 'expiryDate', { type: Date, index: true });
- *     db.defineProperty('Content', 'isExpired', { type: Boolean, index: true });
+ *     db.defineProperty('Content', 'competitionType',
+ *       { type: String });
+ *     db.defineProperty('Content', 'expiryDate',
+ *       { type: Date, index: true });
+ *     db.defineProperty('Content', 'isExpired',
+ *       { type: Boolean, index: true });
  *```
- * The extendModel() method enables you to extend the content model with competition attributes.
+ * This method enables you to extend a model as follows (for example):
  * ```js
  *     db.extendModel('Content', {
  *       competitionType: String,
@@ -453,7 +471,11 @@ ModelBuilder.prototype.defineProperty = function (model, propertyName, propertyD
  *```
  *
  * @param {String} model Name of model
- * @param {Object} props Hash of properties
+ * @options {Object} properties JSON object specifying properties.  Each property is a key whos value is 
+ * either the [type](http://docs.strongloop.com/display/DOC/LDL+data+types) or `propertyName: {options}`
+ * where the options are described below.
+ * @property {String} type Datatype of property: Must be an [LDL type](http://docs.strongloop.com/display/DOC/LDL+data+types).
+ * @property {Boolean} index True if the property is an index; false otherwise.
  */
 ModelBuilder.prototype.extendModel = function (model, props) {
   var t = this;