Final attempt.

Author: josevalim

README.textile

@@ -11,8 +11,6 @@ This guide describes how to use Active Model serializers to build non-trivial JS
 This guide covers an intermediate topic and assumes familiarity with Rails conventions. It is suitable for applications that expose a
 JSON API that may return different results based on the authorization status of the user.
 
-endprologue.
-
 h3. Serialization
 
 By default, Active Record objects can serialize themselves into JSON by using the `to_json` method. This method takes a series of additional
@@ -37,7 +35,7 @@ h3. The Most Basic Serializer
 
 A basic serializer is a simple Ruby object named after the model class it is serializing.
 
-<code><pre>
+<pre><code>
 class PostSerializer
   def initialize(post, scope)
     @post, @scope = post, scope
@@ -47,22 +45,22 @@ class PostSerializer
     { post: { title: @post.name, body: @post.body } }
   end
 end
-</pre></code>
+</code></pre>
 
 A serializer is initialized with two parameters: the model object it should serialize and an authorization scope. By default, the
 authorization scope is the current user (+current_user+) but you can use a different object if you want. The serializer also
 implements an +as_json+ method, which returns a Hash that will be sent to the JSON encoder.
 
 Rails will transparently use your serializer when you use +render :json+ in your controller.
 
-<code><pre>
+<pre><code>
 class PostsController < ApplicationController
   def show
     @post = Post.find(params[:id])
     render json: @post
   end
 end
-</pre></code>
+</code></pre>
 
 Because +respond_with+ uses +render :json+ under the hood for JSON requests, Rails will automatically use your serializer when
 you use +respond_with+ as well.
@@ -72,7 +70,7 @@ h4. +serializable_hash+
 In general, you will want to implement +serializable_hash+ and +as_json+ to allow serializers to embed associated content
 directly. The easiest way to implement these two methods is to have +as_json+ call +serializable_hash+ and insert the root.
 
-<code><pre>
+<pre><code>
 class PostSerializer
   def initialize(post, scope)
     @post, @scope = post, scope
@@ -86,14 +84,14 @@ class PostSerializer
     { post: serializable_hash }
   end
 end
-</pre></code>
+</code></pre>
 
 h4. Authorization
 
 Let's update our serializer to include the email address of the author of the post, but only if the current user has superuser
 access.
 
-<code><pre>
+<pre><code>
 class PostSerializer
   def initialize(post, scope)
     @post, @scope = post, scope
@@ -122,14 +120,14 @@ private
     @scope.superuser?
   end
 end
-</pre></code>
+</code></pre>
 
 h4. Testing
 
 One benefit of encapsulating our objects this way is that it becomes extremely straight-forward to test the serialization
 logic in isolation.
 
-<code><pre>
+<pre><code>
 require "ostruct"
 
 class PostSerializerTest < ActiveSupport::TestCase
@@ -159,7 +157,7 @@ class PostSerializerTest < ActiveSupport::TestCase
     assert_empty hash
   end
 end
-</pre></code>
+</code></pre>
 
 It's important to note that serializer objects define a clear interface specifically for serializing an existing object.
 In this case, the serializer expects to receive a post object with +name+, +body+ and +email+ attributes and an authorization
@@ -170,7 +168,7 @@ the serializer doesn't need to concern itself with how the authorization scope d
 whether it is set. In general, you should document these requirements in your serializer files and programatically via tests.
 The documentation library +YARD+ provides excellent tools for describing this kind of requirement:
 
-<code><pre>
+<pre><code>
 class PostSerializer
   # @param [~body, ~title, ~email] post the post to serialize
   # @param [~super] scope the authorization scope for this serializer
@@ -180,7 +178,7 @@ class PostSerializer
 
   # ...
 end
-</pre></code>
+</code></pre>
 
 h3. Attribute Sugar
 
@@ -191,7 +189,7 @@ For example, you will sometimes want to simply include a number of existing attr
 JSON. In the above example, the +title+ and +body+ attributes were always included in the JSON. Let's see how to use
 +ActiveModel::Serializer+ to simplify our post serializer.
 
-<code><pre>
+<pre><code>
 class PostSerializer < ActiveModel::Serializer
   attributes :title, :body
 
@@ -214,7 +212,7 @@ private
     @scope.superuser?
   end
 end
-</pre></code>
+</code></pre>
 
 First, we specified the list of included attributes at the top of the class. This will create an instance method called
 +attributes+ that extracts those attributes from the post model.
@@ -225,7 +223,7 @@ Next, we use the attributes methood in our +serializable_hash+ method, which all
 earlier. We could also eliminate the +as_json+ method, as +ActiveModel::Serializer+ provides a default +as_json+ method for
 us that calls our +serializable_hash+ method and inserts a root. But we can go a step further!
 
-<code><pre>
+<pre><code>
 class PostSerializer < ActiveModel::Serializer
   attributes :title, :body
 
@@ -240,7 +238,7 @@ private
     @scope.superuser?
   end
 end
-</pre></code>
+</code></pre>
 
 The superclass provides a default +initialize+ method as well as a default +serializable_hash+ method, which uses
 +attributes+. We can call +super+ to get the hash based on the attributes we declared, and then add in any additional
@@ -253,7 +251,7 @@ h3. Associations
 In most JSON APIs, you will want to include associated objects with your serialized object. In this case, let's include
 the comments with the current post.
 
-<code><pre>
+<pre><code>
 class PostSerializer < ActiveModel::Serializer
   attributes :title, :body
   has_many :comments
@@ -269,11 +267,11 @@ private
     @scope.superuser?
   end
 end
-</pre></code>
+</code></pre>
 
 The default +serializable_hash+ method will include the comments as embedded objects inside the post.
 
-<code><pre>
+<pre><code>
 {
   post: {
     title: "Hello Blog!",
@@ -286,14 +284,14 @@ The default +serializable_hash+ method will include the comments as embedded obj
     ]
   }
 }
-</pre></code>
+</code></pre>
 
 Rails uses the same logic to generate embedded serializations as it does when you use +render :json+. In this case,
 because you didn't define a +CommentSerializer+, Rails used the default +as_json+ on your comment object.
 
 If you define a serializer, Rails will automatically instantiate it with the existing authorization scope.
 
-<code><pre>
+<pre><code>
 class CommentSerializer
   def initialize(comment, scope)
     @comment, @scope = comment, scope
@@ -307,26 +305,26 @@ class CommentSerializer
     { comment: serializable_hash }
   end
 end
-</pre></code>
+</code></pre>
 
 If we define the above comment serializer, the outputted JSON will change to:
 
-<code><pre>
+<pre><code>
 {
   post: {
     title: "Hello Blog!",
     body: "This is my first post. Isn't it fabulous!",
     comments: [{ title: "Awesome" }]
   }
 }
-</pre></code>
+</code></pre>
 
 Let's imagine that our comment system allows an administrator to kill a comment, and we only want to allow
 users to see the comments they're entitled to see. By default, +has_many :comments+ will simply use the
 +comments+ accessor on the post object. We can override the +comments+ accessor to limit the comments used
 to just the comments we want to allow for the current user.
 
-<code><pre>
+<pre><code>
 class PostSerializer < ActiveModel::Serializer
   attributes :title. :body
   has_many :comments
@@ -346,7 +344,7 @@ private
     @scope.superuser?
   end
 end
-</pre></code>
+</code></pre>
 
 +ActiveModel::Serializer+ will still embed the comments, but this time it will use just the comments
 for the current user.
@@ -361,7 +359,7 @@ build up the hash manually.
 
 For example, let's say our front-end expects the posts and comments in the following format:
 
-<code><pre>
+<pre><code>
 {
   post: {
     id: 1
@@ -382,11 +380,11 @@ For example, let's say our front-end expects the posts and comments in the follo
     }
   ]
 }
-</pre></code>
+</code></pre>
 
 We could achieve this with a custom +as_json+ method. We will also need to define a serializer for comments.
 
-<code><pre>
+<pre><code>
 class CommentSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
 
@@ -422,7 +420,7 @@ private
     @scope.superuser?
   end
 end
-</pre></code>
+</code></pre>
 
 Here, we used two convenience methods: +associations+ and +association_ids+. The first,
 +associations+, creates a hash of all of the define associations, using their defined
@@ -444,7 +442,7 @@ For instance, we might want to provide the full comment when it is requested dir
 but only its title when requested as part of the post. To achieve this, you can define
 a serializer for associated objects nested inside the main serializer.
 
-<code><pre>
+<pre><code>
 class PostSerializer < ActiveModel::Serializer
   class CommentSerializer < ActiveModel::Serializer
     attributes :id, :title
@@ -453,7 +451,7 @@ class PostSerializer < ActiveModel::Serializer
   # same as before
   # ...
 end
-</pre></code>
+</code></pre>
 
 In other words, if a +PostSerializer+ is trying to serialize comments, it will first
 look for +PostSerializer::CommentSerializer+ before falling back to +CommentSerializer+
@@ -470,11 +468,11 @@ its +current_user+ method and pass that along to the serializer's initializer.
 If you want to change that behavior, simply use the +serialization_scope+ class
 method.
 
-<code><pre>
+<pre><code>
 class PostsController < ApplicationController
   serialization_scope :current_app
 end
-</pre></code>
+</code></pre>
 
 You can also implement an instance method called (no surprise) +serialization_scope+,
 which allows you to define a dynamic authorization scope based on the current request.
@@ -491,19 +489,19 @@ outside a request.
 For instance, if you want to generate the JSON representation of a post for a user outside
 of a request:
 
-<code><pre>
+<pre><code>
 user = get_user # some logic to get the user in question
 PostSerializer.new(post, user).to_json # reliably generate JSON output
-</pre></code>
+</code></pre>
 
 If you want to generate JSON for an anonymous user, you should be able to use whatever
 technique you use in your application to generate anonymous users outside of a request.
 Typically, that means creating a new user and not saving it to the database:
 
-<code><pre>
+<pre><code>
 user = User.new # create a new anonymous user
 PostSerializer.new(post, user).to_json
-</pre></code>
+</code></pre>
 
 In general, the better you encapsulate your authorization logic, the more easily you
 will be able to use the serializer outside of the context of a request. For instance,
@@ -521,7 +519,7 @@ as the root).
 
 For example, an Array of post objects would serialize as:
 
-<code><pre>
+<pre><code>
 {
   posts: [
     {
@@ -533,12 +531,12 @@ For example, an Array of post objects would serialize as:
     }
   ]
 }
-</pre></code>
+</code></pre>
 
 If you want to change the behavior of serialized Arrays, you need to create
 a custom Array serializer.
 
-<code><pre>
+<pre><code>
 class ArraySerializer < ActiveModel::ArraySerializer
   def serializable_array
     serializers.map do |serializer|
@@ -552,7 +550,7 @@ class ArraySerializer < ActiveModel::ArraySerializer
     hash
   end
 end
-</pre></code>
+</code></pre>
 
 When generating embedded associations using the +associations+ helper inside a
 regular serializer, it will create a new <code>ArraySerializer</code> with the