From 4e484327054aba7013dee1fcc06d5611c905b38c Mon Sep 17 00:00:00 2001
From: Raymond Feng <raymond@strongloop.com>
Date: Thu, 24 Oct 2013 09:06:46 -0700
Subject: [PATCH] Add belongsTo and hasAndBelongsToMany

---
 docs/api.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/docs/api.md b/docs/api.md
index 324693f2..3484aabb 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -641,7 +641,7 @@ The express ServerResponse object. [See full documentation](http://expressjs.com
     
 #### Relationships
 
-##### Model.hasMany(Model)
+##### Model.hasMany(Model, options)
 
 Define a "one to many" relationship.
 
@@ -682,6 +682,42 @@ Book.create(function(err, book) {
   });
 });
 ```
+
+##### Model.belongsTo(Model, options)
+
+A `belongsTo` relation 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. For example, if your application includes users and posts, and each post
+can be written by exactly one user.
+
+```js
+    Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});
+```
+
+The code above basically says Post has a reference called `author` to User using
+the `userId` property of Post as the foreign key. Now we can access the author
+in one of the following styles:
+
+```js
+    post.author(callback); // Get the User object for the post author asynchronously
+    post.author(); // Get the User object for the post author synchronously
+    post.author(user) // Set the author to be the given user
+```
+
+##### Model.hasAndBelongsToMany(Model, options)
+
+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,
+
+```js
+    User.hasAndBelongsToMany('groups', {model: Group, foreignKey: 'groupId'});
+    user.groups(callback); // get groups of the user
+    user.groups.create(data, callback); // create a new group and connect it with the user
+    user.groups.add(group, callback); // connect an existing group with the user
+    user.groups.remove(group, callback); // remove the user from the group
+```
     
 #### Shared Methods