From afe3c938070dc5c532d6f41eec3a470aec7afc5b Mon Sep 17 00:00:00 2001
From: Benjamin Fleischer <bf4@users.noreply.github.com>
Date: Sun, 10 Apr 2016 12:44:37 -0500
Subject: [PATCH] Add more association documentation (#1635)

[DOC] Add more association documentation
---
 docs/general/serializers.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/general/serializers.md b/docs/general/serializers.md
index fe50a486..daf6a9a6 100644
--- a/docs/general/serializers.md
+++ b/docs/general/serializers.md
@@ -38,6 +38,26 @@ Serialization of the resource `title`
 
 ### Associations
 
+The interface for associations is, generically:
+
+> `association_type(association_name, options, &block)`
+
+Where:
+
+- `association_type` may be `has_one`, `has_many`, `belongs_to`.
+- `association_name` is a method name the serializer calls.
+- optional: `options` may be:
+  - `key:` The name used for the serialized association.
+  - `serializer:`
+  - `if:`
+  - `unless:`
+  - `virtual_value:`
+- optional: `&block` is a context that returns the association's attributes.
+  - prevents `association_name` method from being called.
+  - return value of block is used as the association value.
+  - yields the `serializer` to the block.
+  - `include_data false` prevents the `data` key from being rendered in the JSON API relationship.
+
 #### ::has_one
 
 e.g.
@@ -58,6 +78,14 @@ def cached_blog
 end
 ```
 
+``ruby
+has_one :blog, if: :show_blog?
+
+def show_blog?
+  scope.admin?
+end
+```
+
 #### ::has_many
 
 e.g.