From 1a5e66b933f20c2abf4ba399a9803d11ea83dc98 Mon Sep 17 00:00:00 2001
From: Timur <charlie.vmk@gmail.com>
Date: Tue, 28 Mar 2017 13:14:50 +0600
Subject: [PATCH] [0.10] add docs for include (#2081)

* Add docs for `include` option in the adapter
---
 CHANGELOG.md             |  2 ++
 docs/general/adapters.md | 34 +++++++++++++++++++++++++---------
 2 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f6ea953..a4685842 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,8 @@ Fixes:
 
 Misc:
 
+- [#2081](https://github.com/rails-api/active_model_serializers/pull/2081) Documentation for `include` option in adapters. (@charlie-wasp)
+
 ### [v0.10.5 (2017-03-07)](https://github.com/rails-api/active_model_serializers/compare/v0.10.4...v0.10.5)
 
 Breaking changes:
diff --git a/docs/general/adapters.md b/docs/general/adapters.md
index 6ae1d27a..84fc4e62 100644
--- a/docs/general/adapters.md
+++ b/docs/general/adapters.md
@@ -141,18 +141,25 @@ This adapter follows **version 1.0** of the [format specified](../jsonapi/schema
 }
 ```
 
-#### Included
+### Include option
 
-It will include the associated resources in the `"included"` member
-when the resource names are included in the `include` option.
-Including nested associated resources is also supported.
+Which [serializer associations](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#associations) are rendered can be specified using the `include` option. The option usage is consistent with [the include option in the JSON API spec](http://jsonapi.org/format/#fetching-includes), and is available in all adapters.
 
+Example of the usage:
 ```ruby
   render json: @posts, include: ['author', 'comments', 'comments.author']
   # or
   render json: @posts, include: 'author,comments,comments.author'
 ```
 
+The format of the `include` option can be either:
+
+- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
+- an Array of Symbols and Hashes.
+- a mix of both.
+
+An empty string or an empty array will prevent rendering of any associations.
+
 In addition, two types of wildcards may be used:
 
 - `*` includes one level of associations.
@@ -164,11 +171,6 @@ These can be combined with other paths.
   render json: @posts, include: '**' # or '*' for a single layer
 ```
 
-The format of the `include` option can be either:
-
-- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
-- an Array of Symbols and Hashes.
-- a mix of both.
 
 The following would render posts and include:
 
@@ -182,6 +184,20 @@ It could be combined, like above, with other paths in any combination desired.
   render json: @posts, include: 'author.comments.**'
 ```
 
+**Note:** Wildcards are ActiveModelSerializers-specific, they are not part of the JSON API spec.
+
+The default include for the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations.
+
+For the JSON API adapter associated resources will be gathered in the `"included"` member. For the JSON and Attributes
+adapters associated resources will be rendered among the other attributes.
+
+Only for the JSON API adapter you can specify, which attributes of associated resources will be rendered. This feature
+is called [sparse fieldset](http://jsonapi.org/format/#fetching-sparse-fieldsets):
+
+```ruby
+  render json: @posts, include: 'comments', fields: { comments: ['content', 'created_at'] }
+```
+
 ##### Security Considerations
 
 Since the included options may come from the query params (i.e. user-controller):