Updated JSDoc comments with content from .md file

lib/relations.js

@@ -8,7 +8,7 @@ var ModelBaseClass = require('./model.js');
 module.exports = Relation;
 
 /**
- * Relations class
+ * Relations class.  Use to define relationships between models.
  *
  * @class Relation
  */
@@ -47,12 +47,25 @@ function lookupModel(models, modelName) {
 }
 
 /**
- * Declare "hasMany" relation.
- * Example:
- * ```User.hasMany(Post, {as: 'posts', foreignKey: 'authorId'});```
+ * Define a "one to many" relationship by specifying the model name
  * 
+ * Examples:
+ * ```
+ * User.hasMany(Post, {as: 'posts', foreignKey: 'authorId'});
+ * ```
+ * 
+ * ```
+ * Book.hasMany(Chapter);
+ * ```
+ * Or, equivalently:
+ * ```
+ * Book.hasMany('chapters', {model: Chapter});
+ * ```
  * @param {Relation} anotherClass Class to has many
- * @param {Object} params Configuration {as:, foreignKey:}
+ * @options {Object} parameters Configuration parameters 
+ * @property {String} as
+ * @property {String} foreignKey Property name of foreign key field.
+ * @property {Object} model Model object
  */
 Relation.hasMany = function hasMany(anotherClass, params) {
   var thisClassName = this.modelName;
@@ -218,9 +231,28 @@ Relation.hasMany = function hasMany(anotherClass, params) {
 };
 
 /**
- * Declare "belongsTo" relation.
+ * Declare "belongsTo" relation that sets up a one-to-one connection with another model, such that each
+ * instance of the declaring model "belongs to" one instance of the other model.
  *
- * **Examples**
+ * For example, if an application includes users and posts, and each post can be written by exactly one user.
+ * The following code specifies that `Post` has a reference called `author` to the `User` model via the `userId` property of `Post`
+ * as the foreign key.
+ * ```
+ * Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});
+ * ```
+ * You can then access the author in one of the following styles.
+ * Get the User object for the post author asynchronously:
+ * ```
+ * post.author(callback);
+ * ```
+ * Get the User object for the post author synchronously:
+ * ```
+ * post.author();
+ * Set the author to be the given user:
+ * ```
+ * post.author(user) 
+ * ```
+ * Examples:
  * 
  * Suppose the model Post has a *belongsTo* relationship with User (the author of the post). You could declare it this way:
  * ```js
@@ -244,7 +276,9 @@ Relation.hasMany = function hasMany(anotherClass, params) {
  * This optional parameter default value is false, so the related object will be loaded from cache if available.
  * 
  * @param {Class} anotherClass Class to belong
- * @param {Object} params Configuration {as: 'propertyName', foreignKey: 'keyName'}
+ * @param {Object} Parameters Configuration parameters
+ * @property {String} as Can be 'propertyName'
+ * @property {String} foreignKey Name of foreign key property.
  * 
  */
 Relation.belongsTo = function (anotherClass, params) {
@@ -389,15 +423,34 @@ Relation.belongsTo = function (anotherClass, params) {
 };
 
 /**
- * Many-to-many relation
- *
- * For example, this creates connection model 'PostTag':
- * ```js
- * Post.hasAndBelongsToMany('tags');
- * ``` 
+ * A hasAndBelongsToMany relation creates a direct many-to-many connection with another model, with no intervening model.
+ * For example, if your application includes users and groups, with each group having many users and each user appearing
+ * in many groups, you could declare the models this way:
+ * ```
+ *  User.hasAndBelongsToMany('groups', {model: Group, foreignKey: 'groupId'});
+ * ```
+ *  Then, to get the groups to which the user belongs:
+ * ```
+ *  user.groups(callback);
+ * ```
+ *  Create a new group and connect it with the user:
+ * ```
+ *  user.groups.create(data, callback);
+ * ```
+ *  Connect an existing group with the user:
+ * ```
+ *  user.groups.add(group, callback);
+ * ```
+ *  Remove the user from the group:
+ * ```
+ *  user.groups.remove(group, callback); 
+ * ```
+ * 
  * @param {String|Function} anotherClass - target class to hasAndBelongsToMany or name of
  * the relation
- * @param {Object} params - configuration {as: String, foreignKey: *, model: ModelClass}
+ * @options {Object} params - configuration {as: String, foreignKey: *, model: ModelClass}
+ * @property {Object} model Model name
+ * @property {String} foreignKey Property name of foreign key field.
  */
 Relation.hasAndBelongsToMany = function hasAndBelongsToMany(anotherClass, params) {
   params = params || {};