From 177752e144a6f53febc5342588bb20ad7caa4d29 Mon Sep 17 00:00:00 2001
From: Raymond Feng <raymond@strongloop.com>
Date: Thu, 19 Jun 2014 11:13:24 -0700
Subject: [PATCH] Add more jsdocs

---
 lib/relation-definition.js | 49 ++++++++++++++++++++++++++++----------
 test/relations.test.js     |  1 -
 2 files changed, 36 insertions(+), 14 deletions(-)

diff --git a/lib/relation-definition.js b/lib/relation-definition.js
index 38c52c93..13366d7a 100644
--- a/lib/relation-definition.js
+++ b/lib/relation-definition.js
@@ -631,17 +631,19 @@ BelongsTo.prototype.related = function (refresh, params) {
 };
 
 /**
- * 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:
+ * 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'});
  * ```
  * 
- * @param {String|Object} modelTo Model object (or String name of model) to which you are creating the relationship.
- * the relation
+ * @param {String|Object} modelTo Model object (or String name of model) to
+ * which you are creating the relationship.
  * @options {Object} params Configuration parameters; see below.
- * @property {String} as Name of the property in the referring model that corresponds to the foreign key field in the related model.
+ * @property {String} as Name of the property in the referring model that
+ * corresponds to the foreign key field in the related model.
  * @property {String} foreignKey Property name of foreign key field.
  * @property {Object} model Model object
  */
@@ -676,10 +678,19 @@ RelationDefinition.hasAndBelongsToMany = function hasAndBelongsToMany(modelFrom,
 };
 
 /**
- * HasOne
- * @param modelFrom
- * @param modelTo
- * @param params
+ * A HasOne relation creates a one-to-one connection from modelFrom to modelTo.
+ * This relation indicates that each instance of a model contains or possesses
+ * one instance of another model. For example, each supplier in your application
+ * has only one account.
+ *
+ * @param {Function} modelFrom The declaring model class
+ * @param {String|Function} modelTo Model object (or String name of model) to
+ * which you are creating the relationship.
+ * @options {Object} params Configuration parameters; see below.
+ * @property {String} as Name of the property in the referring model that
+ * corresponds to the foreign key field in the related model.
+ * @property {String} foreignKey Property name of foreign key field.
+ * @property {Object} model Model object
  */
 RelationDefinition.hasOne = function (modelFrom, modelTo, params) {
   params = params || {};
@@ -723,6 +734,13 @@ RelationDefinition.hasOne = function (modelFrom, modelTo, params) {
   });
 };
 
+/**
+ * Create a target model instance
+ * @param {Object} targetModelData The target model data
+ * @callback {Function} [cb] Callback function
+ * @param {String|Object} err Error string or object
+ * @param {Object} The newly created target model instance
+ */
 HasOne.prototype.create = function(targetModelData, cb) {
   var modelTo = this.definition.modelTo;
   var fk = this.definition.keyTo;
@@ -740,6 +758,11 @@ HasOne.prototype.create = function(targetModelData, cb) {
   });
 };
 
+/**
+ * Build a target model instance
+ * @param {Object} targetModelData The target model data
+ * @returns {Object} The newly built target model instance
+ */
 HasOne.prototype.build = function(targetModelData) {
   var modelTo = this.definition.modelTo;
   var pk = this.definition.keyFrom;
@@ -756,9 +779,9 @@ HasOne.prototype.build = function(targetModelData) {
  * - order.customer(customer): Synchronous setter of the target model instance
  * - order.customer(): Synchronous getter of the target model instance
  *
- * @param refresh
- * @param params
- * @returns {*}
+ * @param {Boolean} refresh Reload from the data source
+ * @param {Object|Function} params Query parameters
+ * @returns {Object}
  */
 HasOne.prototype.related = function (refresh, params) {
   var modelTo = this.definition.modelTo;
diff --git a/test/relations.test.js b/test/relations.test.js
index d0cd0ea9..4e1f5873 100644
--- a/test/relations.test.js
+++ b/test/relations.test.js
@@ -193,7 +193,6 @@ describe('relations', function () {
       Supplier.hasOne(Account);
       Object.keys((new Account()).toObject()).should.include('supplierId');
       (new Supplier()).account.should.be.an.instanceOf(Function);
-
     });
 
     it('can be used to query data', function (done) {