From aa619b5e0e571ae94c586d57fd182c0f6cf4e628 Mon Sep 17 00:00:00 2001
From: Cassidy K <cassidy@fastmail.com>
Date: Tue, 11 Apr 2017 16:01:21 -0400
Subject: [PATCH] Update Serializers and Rendering Docs

- Updating general/serializers.md
- Updating docs/general/rendering.md
- adding to changelog
- Updating rendering.md to indicate that `each_serializer` must be used on a collection
- updating my handle in previous changelog entry
---
 CHANGELOG.md                |  3 ++-
 docs/general/rendering.md   | 22 ++++++++++++++++++----
 docs/general/serializers.md | 19 +++++++++++++++++--
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a4685842..fc263078 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ Fixes:
 
 Misc:
 
+- [#2104](https://github.com/rails-api/active_model_serializers/pull/2104) Documentation for serializers and rendering. (@cassidycodes)
 - [#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)
@@ -79,7 +80,7 @@ Misc:
 
 - [#1878](https://github.com/rails-api/active_model_serializers/pull/1878) Cache key generation for serializers now uses `ActiveSupport::Cache.expand_cache_key` instead of `Array#join` by default and is also overridable. This change should be backward-compatible. (@markiz)
 
-- [#1799](https://github.com/rails-api/active_model_serializers/pull/1799) Add documentation for setting the adapter. (@ScottKbka)
+- [#1799](https://github.com/rails-api/active_model_serializers/pull/1799) Add documentation for setting the adapter. (@cassidycodes)
 - [#1909](https://github.com/rails-api/active_model_serializers/pull/1909) Add documentation for relationship links. (@vasilakisfil, @NullVoxPopuli)
 - [#1959](https://github.com/rails-api/active_model_serializers/pull/1959) Add documentation for root. (@shunsuke227ono)
 - [#1967](https://github.com/rails-api/active_model_serializers/pull/1967) Improve type method documentation. (@yukideluxe)
diff --git a/docs/general/rendering.md b/docs/general/rendering.md
index 21120a5a..af2d886f 100644
--- a/docs/general/rendering.md
+++ b/docs/general/rendering.md
@@ -203,7 +203,7 @@ link(:link_name) { url_for(controller: 'controller_name', action: 'index', only_
 
 #### include
 
-PR please :)
+See [Adapters: Include Option](/docs/general/adapters.md#include-option).
 
 #### Overriding the root key
 
@@ -260,15 +260,29 @@ Note that by using a string and symbol, Ruby will assume the namespace is define
 
 #### serializer
 
-PR please :)
+Specify which serializer to use if you want to use a serializer other than the default.
+
+For a single resource:
+
+```ruby
+@post = Post.first
+render json: @post, serializer: SpecialPostSerializer
+```
+
+To specify which serializer to use on individual items in a collection (i.e., an `index` action), use `each_serializer`:
+
+```ruby
+@posts = Post.all
+render json: @posts, each_serializer: SpecialPostSerializer
+```
 
 #### scope
 
-PR please :)
+See [Serializers: Scope](/docs/general/serializers.md#scope).
 
 #### scope_name
 
-PR please :)
+See [Serializers: Scope](/docs/general/serializers.md#scope).
 
 ## Using a serializer without `render`
 
diff --git a/docs/general/serializers.md b/docs/general/serializers.md
index bb6e21be..1d968183 100644
--- a/docs/general/serializers.md
+++ b/docs/general/serializers.md
@@ -382,11 +382,26 @@ The serialized value for a given key. e.g. `read_attribute_for_serialization(:ti
 
 #### #links
 
-PR please :)
+Allows you to modify the `links` node. By default, this node will be populated with the attributes set using the [::link](#link) method. Using `links: nil` will remove the `links` node.
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(
+  @post,
+  adapter: :json_api,
+  links: {
+    self: {
+      href: 'http://example.com/posts',
+      meta: {
+        stuff: 'value'
+      }
+    }
+  }
+)
+```
 
 #### #json_key
 
-PR please :)
+Returns the key used by the adapter as the resource root. See [root](#root) for more information.
 
 ## Examples