[DOCS] Refactor, update, create documentation [ci skip]

Author: bf4

README.md

@@ -1,25 +1,28 @@
 # Docs - ActiveModel::Serializer 0.10.x
 
-This is the documentation of AMS, it's focused on the **0.10.x version.**
+This is the documentation of ActiveModelSerializers, it's focused on the **0.10.x version.**
 
 -----
 
 ## General
 
 - [Getting Started](general/getting_started.md)
-- [Adapters](general/adapters.md)
 - [Configuration Options](general/configuration_options.md)
+- [Serializers](general/serializers.md)
+- [Adapters](general/adapters.md)
+- [Rendering](general/rendering.md)
+- [Caching](general/caching.md)
 - [Logging](general/logging.md)
 - [Instrumentation](general/instrumentation.md)
 
 ## How to
 
 - [How to add root key](howto/add_root_key.md)
 - [How to add pagination links](howto/add_pagination_links.md)
-- [Using AMS Outside Of Controllers](howto/outside_controller_use.md)
+- [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 
 ## Integrations
-| Integration | Supported AMS versions |  Gem name and/or link
+| Integration | Supported ActiveModelSerializers versions |  Gem name and/or link
 |----|-----|----
 | Ember.js | 0.9.x | [active-model-adapter](https://github.com/ember-data/active-model-adapter)
 | Ember.js | 0.10.x + |  [docs/integrations/ember-and-json-api.md](integrations/ember-and-json-api.md)

docs/README.md

@@ -1,9 +1,38 @@
 # Adapters
 
-AMS works through two components: **serializers** and **adapters**.
-Serializers describe _which_ attributes and relationships should be serialized.
-Adapters describe _how_ attributes and relationships should be serialized.
-You can use one of the built-in adapters (```Attributes``` is the default one) or create one by yourself, but you won't need to implement an adapter unless you wish to use a new format or media type with AMS.
+ActiveModelSerializers offers the ability to configure which adapter
+to use both globally and/or when serializing (usually when rendering).
+
+The global adapter configuration is set on [`ActiveModelSerializers.config`](configuration_options.md).
+It should be set only once, preferably at initialization.
+
+For example:
+
+```ruby
+ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+```
+
+or
+
+```ruby
+ActiveModelSerializers.config.adapter = :json_api
+```
+
+or
+
+```ruby
+ActiveModelSerializers.config.adapter = :json
+```
+
+The local adapter option is in the format `adapter: adapter`, where `adapter` is
+any of the same values as set globally.
+
+The configured adapter can be set as a symbol, class, or class name, as described in
+[Advanced adapter configuration](adapters.md#Advanced adapter configuration).
+
+The `Attributes` adapter does not include a root key. It is just the serialized attributes.
+
+Use either the `JSON` or `JSON API` adapters if you want the response document to have a root key.
 
 ## Built in Adapters
 
@@ -14,47 +43,89 @@ Doesn't follow any specific convention.
 
 ### JSON
 
-It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly to the objects being serialized.
+The response document always with a root key.
+
+The root key **can't be overridden**, and will be derived from the resource being serialized.
+
 Doesn't follow any specific convention.
 
 ### JSON API
 
 This adapter follows **version 1.0** of the format specified in
-[jsonapi.org/format](http://jsonapi.org/format). It will include the associated
-resources in the `"included"` member when the resource names are included in the
-`include` option.
+[jsonapi.org/format](http://jsonapi.org/format).
+
+#### Included
+
+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.
 
 ```ruby
-render @posts, include: ['authors', 'comments']
+  render @posts, include: ['author', 'comments', 'comments.author']
+  # or
+  render @posts, include: 'author,comments,comments.author'
 ```
 
-or
+In addition, two types of wildcards may be used:
+
+- `*` includes one level of associations.
+- `**` includes all recursively.
+
+These can be combined with other paths.
+
+```ruby
+  render @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:
+
+- the author
+- the author's comments, and
+- every resource referenced by the author's comments (recursively).
+
+It could be combined, like above, with other paths in any combination desired.
+
+```ruby
+  render @posts, include: 'author.comments.**'
+```
+
+##### Security Considerations
+
+Since the included options may come from the query params (i.e. user-controller):
 
 ```ruby
-render @posts, include: 'authors,comments'
+  render @posts, include: params[:include]
 ```
 
-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, or a mix of both.
+The user could pass in `include=**`.
+
+We recommend filtering any user-supplied includes appropriately.
 
 ## Choosing an adapter
 
 If you want to use a specify a default adapter, such as JsonApi, you can change this in an initializer:
 
 ```ruby
-ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
 ```
 
 or
 
 ```ruby
-ActiveModel::Serializer.config.adapter = :json_api
+ActiveModelSerializers.config.adapter = :json_api
 ```
 
 If you want to have a root key for each resource in your responses, you should use the Json or
 JsonApi adapters instead of the default Attributes:
 
 ```ruby
-ActiveModel::Serializer.config.adapter = :json
+ActiveModelSerializers.config.adapter = :json
 ```
 
 ## Advanced adapter configuration

docs/general/adapters.md

@@ -0,0 +1,50 @@
+# Caching
+
+To cache a serializer, call ```cache``` and pass its options.
+The options are the same options of ```ActiveSupport::Cache::Store```, plus
+a ```key``` option that will be the prefix of the object cache
+on a pattern ```"#{key}/#{object.id}-#{object.updated_at}"```.
+
+The cache support is optimized to use the cached object in multiple request. An object cached on a ```show``` request will be reused at the ```index```. If there is a relationship with another cached serializer it will also be created and reused automatically.
+
+**[NOTE] Every object is individually cached.**
+
+**[NOTE] The cache is automatically expired after an object is updated, but it's not deleted.**
+
+```ruby
+cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
+```
+
+Take the example bellow:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'post', expires_in: 3.hours
+  attributes :title, :body
+
+  has_many :comments
+end
+```
+
+On this example every ```Post``` object will be cached with
+the key ```"post/#{post.id}-#{post.updated_at}"```. You can use this key to expire it as you want,
+but in this case it will be automatically expired after 3 hours.
+
+## Fragment Caching
+
+If there is some API endpoint that shouldn't be fully cached, you can still optimise it, using Fragment Cache on the attributes and relationships that you want to cache.
+
+You can define the attribute by using ```only``` or ```except``` option on cache method.
+
+**[NOTE] Cache serializers will be used at their relationships**
+
+Example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'post', expires_in: 3.hours, only: [:title]
+  attributes :title, :body
+
+  has_many :comments
+end
+```

docs/general/caching.md

@@ -1,6 +1,7 @@
 # Configuration Options
 
-The following configuration options can be set on `ActiveModel::Serializer.config` inside an initializer.
+The following configuration options can be set on `ActiveModelSerializers.config`,
+preferably inside an initializer.
 
 ## General
 
@@ -17,3 +18,7 @@ The following configuration options can be set on `ActiveModel::Serializer.confi
     Default: `'1.0'`.
   - `jsonapi_toplevel_meta`: Optional metadata. Not included if empty.
     Default: `{}`.
+
+## Hooks
+
+To run a hook when ActiveModelSerializers is loaded, use `ActiveSupport.on_load(:active_model_serializers) do end`

docs/general/configuration_options.md

@@ -1,21 +1,5 @@
 # Getting Started
 
-## Installation
-
-### ActiveModel::Serializer is already included on Rails >= 5
-
-Add this line to your application's Gemfile:
-
-```
-gem 'active_model_serializers'
-```
-
-And then execute:
-
-```
-$ bundle
-```
-
 ## Creating a Serializer
 
 The easiest way to create a new serializer is to generate a new resource, which
@@ -33,7 +17,7 @@ the serializer generator:
 $ rails g serializer post
 ```
 
-The generated seralizer will contain basic `attributes` and
+The generated serializer will contain basic `attributes` and
 `has_many`/`has_one`/`belongs_to` declarations, based on the model. For example:
 
 ```ruby
@@ -42,7 +26,6 @@ class PostSerializer < ActiveModel::Serializer
 
   has_many :comments
   has_one :author
-
 end
 ```
 
@@ -53,13 +36,20 @@ class CommentSerializer < ActiveModel::Serializer
   attributes :name, :body
 
   belongs_to :post_id
-
 end
 ```
 
+The attribute names are a **whitelist** of attributes to be serialized.
+
+The `has_many`, `has_one`, and `belongs_to` declarations describe relationships between
+resources. By default, when you serialize a `Post`, you will get its `Comments`
+as well.
+
+For more information, see [Serializers](docs/general/serializers.md).
+
 ### Namespaced Models
 
-When serializing a model inside a namespace, such as `Api::V1::Post`, AMS will expect the corresponding serializer to be inside the same namespace (namely `Api::V1::PostSerializer`).
+When serializing a model inside a namespace, such as `Api::V1::Post`, ActiveModelSerializers will expect the corresponding serializer to be inside the same namespace (namely `Api::V1::PostSerializer`).
 
 ### Model Associations and Nested Serializers
 
@@ -69,7 +59,7 @@ class PostSerializer < ActiveModel::Serializer
   has_many :comments
 end
 ```
-AMS will look for `PostSerializer::CommentSerializer` in priority, and fall back to `::CommentSerializer` in case the former does not exist. This allows for more control over the way a model gets serialized as an association of an other model.
+ActiveModelSerializers will look for `PostSerializer::CommentSerializer` in priority, and fall back to `::CommentSerializer` in case the former does not exist. This allows for more control over the way a model gets serialized as an association of an other model.
 
 For example, in the following situation:
 
@@ -86,11 +76,11 @@ class PostSerializer < ActiveModel::Serializer
 end
 ```
 
-AMS will use `PostSerializer::CommentSerializer` (thus including only the `:body_short` attribute) when serializing a `Comment` as part of a `Post`, but use `::CommentSerializer` when serializing a `Comment` directly (thus including `:body, :date, :nb_likes`).
+ActiveModelSerializers will use `PostSerializer::CommentSerializer` (thus including only the `:body_short` attribute) when serializing a `Comment` as part of a `Post`, but use `::CommentSerializer` when serializing a `Comment` directly (thus including `:body, :date, :nb_likes`).
 
 ## Rails Integration
 
-AMS will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like:
+ActiveModelSerializers will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like:
 
 ```ruby
 class PostsController < ApplicationController