rendering.md in active_model_serializers-0.10.0.rc5

- old
+ new

@@ -54,15 +54,15 @@
 See the ActiveModelSerializers::Model for a base class that implements the full
 API for a plain-old Ruby object (PORO).
 
 ## SerializableResource options
 
-The `options` hash passed to `render` or `ActiveModel::SerializableResource.new(resource, options)`
+The `options` hash passed to `render` or `ActiveModelSerializers::SerializableResource.new(resource, options)`
 are partitioned into `serializer_opts` and `adapter_opts`. `adapter_opts` are passed to new Adapters;
 `serializer_opts` are passed to new Serializers.
 
-The `adapter_opts` are specified in [ActiveModel::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model/serializable_resource.rb#L4).
+The `adapter_opts` are specified in [ActiveModelSerializers::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model_serializers/serializable_resource.rb#L5).
 The `serializer_opts` are the remaining options.
 
 (In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
 methods on the resource serialization by the Rails JSON renderer.  They are, therefore, important
 to know about, but not part of ActiveModelSerializers.)
@@ -77,48 +77,150 @@
 
 #### adapter
 
 PR please :)
 
+#### key_transform
+
+```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
+
+See [Key Transforms](key_transforms.md) for more informaiton.
+
 #### meta
 
-If you want a `meta` attribute in your response, specify it in the `render`
-call:
+A `meta` member can be used to include non-standard meta-information. `meta` can
+be utilized in several levels in a response.
 
+##### Top-level
+
+To set top-level `meta` in a response, specify it in the `render` call.
+
 ```ruby
 render json: @post, meta: { total: 10 }
 ```
 
 The key can be customized using `meta_key` option.
 
 ```ruby
 render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
 ```
 
-`meta` will only be included in your response if you are using an Adapter that supports `root`,
-as JsonAPI and Json adapters, the default adapter (Attributes) doesn't have `root`.
+`meta` will only be included in your response if you are using an Adapter that
+supports `root`, e.g., `JsonApi` and `Json` adapters. The default adapter,
+`Attributes` does not have `root`.
 
-#### meta_key
 
-PR please :)
+##### Resource-level
 
+To set resource-level `meta` in a response, define meta in a serializer with one
+of the following methods:
+
+As a single, static string.
+
+```ruby
+meta stuff: 'value'
+```
+
+As a block containing a Hash.
+
+```ruby
+meta do
+  {
+    rating: 4,
+    comments_count: object.comments.count
+  }
+end
+```
+
+
 #### links
 
-PR please :)
+If you wish to use Rails url helpers for link generation, e.g., `link(:resources) { resources_url }`, ensure your application sets
+`Rails.application.routes.default_url_options`.
 
+##### Top-level
+
+JsonApi supports a [links object](http://jsonapi.org/format/#document-links) to be specified at top-level, that you can specify in the `render`:
+
+```ruby
+  links_object = {
+    href: "http://example.com/api/posts",
+    meta: {
+      count: 10
+    }
+  }
+  render json: @posts, links: links_object
+```
+
+That's the result:
+
+```json
+{
+  "data": [
+    {
+      "type": "posts",
+      "id": "1",
+      "attributes": {
+        "title": "JSON API is awesome!",
+        "body": "You should be using JSON API",
+        "created": "2015-05-22T14:56:29.000Z",
+        "updated": "2015-05-22T14:56:28.000Z"
+      }
+    }
+  ],
+  "links": {
+    "href": "http://example.com/api/posts",
+    "meta": {
+      "count": 10
+    }
+  }
+}
+```
+
+This feature is specific to JsonApi, so you have to use the use the [JsonApi Adapter](adapters.md#jsonapi)
+
+
+##### Resource-level
+
+In your serializer, define each link in one of the following methods:
+
+As a static string
+
+```ruby
+link :link_name, 'https://example.com/resource'
+```
+
+As a block to be evaluated. When using Rails, URL helpers are available.
+Ensure your application sets `Rails.application.routes.default_url_options`.
+
+```ruby
+link :link_name_ do
+  "https://example.com/resource/#{object.id}"
+end
+
+link(:link_name) { "https://example.com/resource/#{object.id}" }
+
+link(:link_name) { resource_url(object) }
+
+link(:link_name) { url_for(controller: 'controller_name', action: 'index', only_path: false) }
+
+```
+
 ### serializer_opts
 
 #### include
 
 PR please :)
 
-#### root
+#### Overriding the root key
 
-The resource root is derived from the class name of the resource being serialized.
+Overriding the resource root only applies when using the JSON adapter.
+
+Normally, the resource root is derived from the class name of the resource being serialized.
 e.g. `UserPostSerializer.new(UserPost.new)` will be serialized with the root `user_post` or `user_posts` according the adapter collection pluralization rules.
 
-Specify the root by passing it as an argument to `render`. For example:
+When using the JSON adapter in your initializer (ActiveModelSerializers.config.adapter = :json), or passing in the adapter in your render call, you can specify the root by passing it as an argument to `render`. For example:
 
 ```ruby
   render json: @user_post, root: "admin_post", adapter: :json
 ```
 
@@ -128,10 +230,10 @@
     "admin_post": {
       "title": "how to do open source"
     }
   }
 ```
-Note: the `Attributes` adapter (default) does not include a resource root.
+Note: the `Attributes` adapter (default) does not include a resource root. You also will not be able to create a single top-level root if you are using the :json_api adapter.
 
 #### serializer
 
 PR please :)
 