Address concerns from #1018 commit c59668e

Author: bf4

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 Breaking changes:
 Features:
+- [#1018](https://github.com/rails-api/active_model_serializers/pull/1018) Add more tests and docs for top-level links (@leandrocp)
 Fixes:
 - [#1501](https://github.com/rails-api/active_model_serializers/pull/1501) Adds tests for SerializableResource::use_adapter?,doc typos (@domitian)
 - [#1488](https://github.com/rails-api/active_model_serializers/pull/1488) Require ActiveSupport's string inflections (@nate00)
@@ -66,8 +67,6 @@ Features:
     CollectionSerializer for clarity, add ActiveModelSerializers.config.collection_serializer (@bf4)
 - [#1295](https://github.com/rails-api/active_model_serializers/pull/1295) Add config `serializer_lookup_enabled` that,
   when disabled, requires serializers to explicitly specified. (@trek)
-- [#1247](https://github.com/rails-api/active_model_serializers/pull/1247) Add top-level links (@beauby)
-  * Add more tests and docs for top-level links (@leandrocp)
 
 Fixes:
 

docs/README.md

@@ -23,7 +23,6 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [How to add pagination links](howto/add_pagination_links.md)
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
-- [How to add top-level links](howto/add_top_level_links.md) (```JSON-API``` only)
 
 ## Integrations
 

docs/general/rendering.md

@@ -103,7 +103,46 @@ PR please :)
 
 #### links
 
-PR please :)
+##### How to add top-level links
+
+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)
 
 ### serializer_opts
 

docs/howto/add_top_level_links.md

@@ -65,7 +65,16 @@ def test_nil_toplevel_links
               adapter: :json_api,
               links: nil
             ).serializable_hash
-            assert_equal(nil, hash[:links])
+            refute hash.key?(:links), 'No links key to be output'
+          end
+
+          def test_nil_toplevel_links_json_adapter
+            hash = ActiveModel::SerializableResource.new(
+              @post,
+              adapter: :json,
+              links: nil
+            ).serializable_hash
+            refute hash.key?(:links), 'No links key to be output'
           end
 
           def test_resource_links