add docs for serializing arrays

README.markdown

@@ -88,6 +88,86 @@ To specify a custom serializer for an object, there are 2 options:
   render :json => @post, :serializer => FancyPostSerializer
 ```
 
+## Arrays
+
+In your controllers, when you use `render :json` for an array of objects, AMS will
+use ActiveModel::ArraySerializer (included in this project) as the base serializer,
+and the individual Serializer for the objects contained in that array.
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+end
+
+class PostsController < ApplicationController
+  def index
+    @posts = Post.all
+    render :json => @posts
+  end
+end
+```
+
+Given the example above, the index action will return
+
+```json
+{
+  "posts":
+  [
+    { "title": "Post 1", "body": "Hello!" },
+    { "title": "Post 2", "body": "Goodbye!" }
+  ]
+}
+```
+
+By default, the root element is the name of the controller. For example, PostsController
+generates a root element "posts". To change it:
+
+```ruby
+  render :json => @posts, :root => "some_posts"
+```
+
+You may disable the root element for arrays at the top level, which will result in
+more concise json. To disable the root element for arrays, you have 3 options:
+
+1. Disable root globally for in ArraySerializer. In an initializer:
+
+```ruby
+  ActiveModel::ArraySerializer.root = false
+```
+
+2. Disable root per render call in your controller:
+
+```ruby
+  render :json => @posts, :root => false
+```
+
+3. Create a custom ArraySerializer and render arrays with it:
+
+```ruby
+  class CustomArraySerializer < ActiveModel::ArraySerializer
+    self.root = "items"
+  end
+
+  # controller:
+  render :json => @posts, :serializer => CustomArraySerializer
+```
+
+Disabling the root element of the array with any of the above 3 methods
+will produce
+
+```json
+[
+  { "title": "Post 1", "body": "Hello!" },
+  { "title": "Post 2", "body": "Goodbye!" }
+]
+```
+
+To specify a custom serializer for the items within an array:
+
+```ruby
+  render :json => @posts, :each_serializer => FancyPostSerializer
+```
+
 ## Getting the old version
 
 If you find that your project is already relying on the old rails to_json

lib/active_model/serializer.rb

@@ -32,7 +32,7 @@ module ActiveModel
   # It serializes an Array, checking if each element that implements
   # the +active_model_serializer+ method.
   #
-  # To disable serialization of root elements, in an initializer:
+  # To disable serialization of root elements:
   #
   #     ActiveModel::ArraySerializer.root = false
   #