adapters.md in cheap_ams-0.10.10

- old
+ new

@@ -28,13 +28,15 @@
   render @posts, include: ['authors', 'comments']
   # or
   render @posts, include: 'authors,comments'
 ```
 
+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.
+
 ## Choosing an adapter
 
-If you want to use a different adapter, such as JsonApi, you can change this in an initializer:
+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
 ```
 
@@ -42,10 +44,61 @@
 
 ```ruby
 ActiveModel::Serializer.config.adapter = :json_api
 ```
 
-If you want to have a root key in your responses you should use the Json adapter, instead of the default FlattenJson:
+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 FlattenJson:
 
 ```ruby
 ActiveModel::Serializer.config.adapter = :json
 ```
+
+## Advanced adapter configuration
+
+### Registering an adapter
+
+The default adapter can be configured, as above, to use any class given to it.
+
+An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
+If a symbol, then the adapter must be, e.g. `:great_example`,
+`ActiveModel::Serializer::Adapter::GreatExample`, or registered.
+
+There are two ways to register an adapter:
+
+1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
+register the `Example::UsefulAdapter` as `:useful_adapter`.
+
+```ruby
+module Example
+  class UsefulAdapter < ActiveModel::Serializer::Adapter
+  end
+end
+```
+
+You'll notice that the name it registers is the class name underscored, not the full namespace.
+
+Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
+the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
+
+2) Any class can be registered as an adapter by calling `register` directly on the
+`ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
+`:special_adapter`.
+
+```ruby
+class MyAdapter; end
+ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
+```
+
+### Looking up an adapter
+
+| `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters { adapter_name => adapter_class } |
+| `ActiveModel::Serializer::Adapter.adapters`    | A (sorted) Array of all known adapter_names |
+| `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` |  The adapter_class, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
+| `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
+| `ActiveModel::Serializer.adapter` | a convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
+
+The registered adapter name is always a String, but may be looked up as a Symbol or String.
+Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
+may both be used.
+
+For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/adapter.rb)