From 9ce24bacd12400681c038459307adce1b231696e Mon Sep 17 00:00:00 2001
From: Lucas <lucas.hosseini@gmail.com>
Date: Tue, 25 Jul 2017 08:48:53 +0200
Subject: [PATCH] Update docs.

---
 .../guides/deserialization/defining.html.md   | 182 +-----------------
 .../deserialization/deserializing.html.md     |  20 +-
 source/guides/deserialization/index.html.md   |   9 +-
 source/guides/index.html.md                   |  15 +-
 source/guides/serialization/defining.html.md  |  41 ++--
 source/guides/serialization/index.html.md     |   6 +-
 source/guides/serialization/rendering.html.md |  22 ++-
 source/peeks/_plain.md                        |  17 +-
 source/peeks/_serializable.md                 |   2 +-
 9 files changed, 57 insertions(+), 257 deletions(-)

diff --git a/source/guides/deserialization/defining.html.md b/source/guides/deserialization/defining.html.md
index 25ddc0b..3e1a7bf 100644
--- a/source/guides/deserialization/defining.html.md
+++ b/source/guides/deserialization/defining.html.md
@@ -6,184 +6,4 @@ layout: guides
 Custom deserializable resources are defined by subclassing
 `JSONAPI::Deserializable::Resource` and using its DSL.
 
-Example:
-
-```ruby
-class DeserializablePost < JSONAPI::Deserializable::Resource
-  attribute :date do |attr|
-    { created_at: attr }
-  end
-
-  relationship :author do |_rel, id, type|
-    { user_id: id,
-      user_type: type }
-  end
-
-  relationship :comments do |_rel, ids, _types|
-    { response_ids: ids }
-  end
-end
-
-# Will allow to build the following hash:
-# => {
-#      type: 'posts',
-#      id: '5',
-#      created_at: '2016-11-18',
-#      title: 'Hello JSON API',
-#      user_id: '12',
-#      user_type: 'users',
-#      response_ids: ['54', '32', '72']
-#    }
-```
-
-The principle is simple: the payload elements for which a custom deserialization
-scheme was defined will use that, while other fields will be deserialized using
-the default deserialization scheme (which can itself be configured).
-
-Note: If the targeted element does not exist in the payload, the corresponding
-fields are not defined.
-
-## Type
-
-The type of the primary data can be accessed via the `type` DSL method.
-
-Example:
-
-```ruby
-class DeserializablePost < JSONAPI::Deserializable::Post
-  # ...
-  type do |t|
-    { primary_type: t.capitalize }
-  end
-end
-```
-
-## Id
-
-The id of the primary data can be accessed via the `id` DSL method.
-
-Example:
-
-```ruby
-class DeserializablePost < JSONAPI::Deserializable::Post
-  # ...
-  id do |i|
-    { primary_id: i.to_i }
-  end
-end
-```
-
-## Attributes
-
-Attributes of the primary data can be accessed via the `attribute` DSL method.
-The `attribute` method takes a symbol representing the name of the targeted
-attribute in the input payload, and a block to define field(s) of the resulting
-hash.
-
-Example:
-
-```ruby
-class DeserializablePost < JSONAPI::Deserializable::Post
-  # ...
-  attribute :date do |d|
-    { created_at: d }
-  end
-end
-```
-
-## Relationships
-
-Relationships of the primary data can be accessed via the `has_many` and
-`has_one` DSL methods.
-
-### To-many relationships
-
-The `has_many` DSL method takes a symbol representing the name of the targeted
-relationship in the input payload, and a block to define field(s) of the
-resulting hash. The block is called with three parameters: `relationship` (the
-whole relationship hash of the input payload), `ids` (an array of the ids of
-related resources), and `types` (an array of types of the related resources).
-
-Example:
-
-```ruby
-class DeserializablePost < JSONAPI::Deserializable::Post
-  # ...
-  has_many :comments do |rel, ids, types|
-    { comment_ids: ids,
-      comment_types: types.map(&:capitalize),
-      comment_meta: rel['meta'] }
-  end
-end
-```
-
-### To-one relationships
-
-The `has_one` DSL method takes a symbol representing the name of the targeted
-relationship in the input payload, and a block to define field(s) of the
-resulting hash. The block is called with three parameters: `relationship` (the
-whole relationship hash of the input payload), `id` (the id of the related
-resource), and `type` (the type of the related resource).
-
-Example:
-
-```ruby
-class DeserializablePost < JSONAPI::Deserializable::Post
-  # ...
-  has_one :author do |rel, id, type|
-    { author_id: id,
-      author_type: type.capitalize,
-      author_meta: rel['meta'] }
-  end
-end
-```
-
-## Meta
-
-Not available yet.
-
-## Links
-
-Not available yet.
-
-## Configuration
-
-The default deserialization scheme can be configure in the following way:
-
-```ruby
-# Modifying the global default deserialization scheme
-JSONAPI::Deserializable::Resource.configure do |config|
-  config.default_id   = proc { |id| { id: id } }
-  config.default_type = proc { |type| { type: type } }
-  config.default_attribute = proc do |key, value|
-    { key => value }
-  end
-  config.default_has_one = proc do |key, rel, id, type|
-    { "#{key}_id}".to_sym => id, "#{key}_type".to_sym => type }
-  end
-  config.default_has_many = proc do |key, rel, ids, types|
-    { "#{key}_ids}".to_sym => ids, "#{key}_types".to_sym => types }
-  end
-end
-
-# Modifying the default deserialization scheme of a single deserializable
-#   resource class
-
-class DeserializablePost < JSONAPI::Deserializable::Resource
-  # ...
-end
-
-DeserializablePost.configure do |config|
-  config.default_id   = proc { |id| { id: id } }
-  config.default_type = proc { |type| { type: type } }
-  config.default_attribute = proc do |key, value|
-    { key => value }
-  end
-  config.default_has_one = proc do |key, rel, id, type|
-    { "#{key}_id".to_sym => id, "#{key}_type".to_sym => type }
-  end
-  config.default_has_many = proc do |key, rel, ids, types|
-    { "#{key}_ids".to_sym => ids, "#{key}_types".to_sym => types }
-  end
-end
-```
+Documentation currently being rewritten.
diff --git a/source/guides/deserialization/deserializing.html.md b/source/guides/deserialization/deserializing.html.md
index 4af928d..14f167d 100644
--- a/source/guides/deserialization/deserializing.html.md
+++ b/source/guides/deserialization/deserializing.html.md
@@ -6,23 +6,7 @@ layout: guides
 Deserializing an input payload is straightforward: simply call the
 deserializable resource.
 
-Example (generic deserializable resource):
-
-```ruby
-JSONAPI::Deserializable::Resource.call(json_hash)
-# => {
-#      type: 'posts',
-#      id: '5',
-#      title: 'Hello JSON API',
-#      date: '2016-11-18',
-#      author_id: '12',
-#      author_type: 'users',
-#      comments_ids: ['54', '32', '72']
-#      comments_types: ['comments', 'comments', 'comments']
-#    }
-```
-
-Example (custom deserializable resource):
+Example:
 
 ```ruby
 DeserializablePost.call(json_hash)
@@ -58,7 +42,7 @@ Example:
 
 ```ruby
 class PostsController < ApplicationController
-  deserializable_resource :post, DeserializablePost, only: [:create, :update]
+  deserializable_resource :post, class: DeserializablePost, only: [:create, :update]
 
   # ...
 
diff --git a/source/guides/deserialization/index.html.md b/source/guides/deserialization/index.html.md
index 829a9f7..ca7ca26 100644
--- a/source/guides/deserialization/index.html.md
+++ b/source/guides/deserialization/index.html.md
@@ -3,12 +3,9 @@ layout: guides
 ---
 # Deserialization
 
-Any resource payload can be deserialized into a standardized format using the
-`JSONAPI::Deserializable::Resource` class. In case you need more control over
-the generated hash (modifying some field names, or modifying the default
-deserialization scheme for attributes/relationships), you can define custom
-*deserializable resources*. Deserializable resources map the members of a
-payload to fields of a hash. They are defined via an intuitive DSL.
+Deserializable resources map the members of a payload to fields of a hash.
+They are defined by subclassing `JSONAPI::Deserializable::Resource` via an
+intuitive DSL.
 
 Once your deserializable resources are defined, you can call them on hashes
 representing input JSON API payloads, and obtain a hash that you can use
diff --git a/source/guides/index.html.md b/source/guides/index.html.md
index 382044b..6e31154 100644
--- a/source/guides/index.html.md
+++ b/source/guides/index.html.md
@@ -15,7 +15,8 @@ validation of JSON API documents,
 + [jsonapi-renderer](https://github.com/jsonapi-rb/renderer) for low-level
 rendering of JSON API documents,
 + [jsonapi-serializable](https://github.com/jsonapi-rb/serializable) for
-building serializable resource classes from your business object,
+building serializable resource classes from your business object -- those are
+usually referred to as "serializers" in other libs,
 + [jsonapi-deserializable](https://github.com/jsonapi-rb/deserializable) for
 building deserializable resource classes that transform an incoming JSON API
 payload into a custom hash,
@@ -29,18 +30,6 @@ generators,
 [Hanami](http://hanamirb.org) with Hanami::Controller::Action integration and
 (soon) generators.
 
-## Overview
-
-jsonapi-rb works by defining *mappers* (or *presenters*) to translate your
-business objects to JSON API documents, and JSON API payloads to custom hashes.
-
-The *deserializable resources* (the mappers from JSON API payloads to custom
-hashes) can be used directly, as the input payload will only contain flat data.
-
-The *serializable resources*, on the other hand, need to be coordinated through
-a *renderer* (as JSON API response document usually contain a graph of resources
-related to each other).
-
 ## Guides
 
 These guides should get you up to speed with using jsonapi-rb. If you have more
diff --git a/source/guides/serialization/defining.html.md b/source/guides/serialization/defining.html.md
index e51a779..d5064ef 100644
--- a/source/guides/serialization/defining.html.md
+++ b/source/guides/serialization/defining.html.md
@@ -20,7 +20,7 @@ class SerializablePost < JSONAPI::Serializable::Resource
 
   belongs_to :author
 
-  has_many :comments, class: 'V2::SerializableComment' do
+  has_many :comments do
     data do
       @object.published_comments
     end
@@ -45,18 +45,19 @@ end
 ```
 
 The principle is simple: you declare elements of the JSON API resource and
-specify their values.
+optionally specify their values.
 
 The underying object is available throughout the DSL as the instance variable
 `@object`. (In general, all *exposures* - that is, variables made available in
-the `render` call - are available throughout the DSL as instance variables.)
+the `render` call via the `expose` option - are available throughout the DSL
+as instance variables.)
 
 ## Type
 
 The `type` property is declared via the DSL method of the same name, and takes
-a symbol or a string.
+a symbol, a string, or a block.
 
-Example:
+Examples:
 
 ```ruby
 class SerializablePost < JSONAPI::Serializable::Resource
@@ -64,6 +65,12 @@ class SerializablePost < JSONAPI::Serializable::Resource
 end
 ```
 
+```ruby
+class SerializablePost < JSONAPI::Serializable::Resource
+  type { @object.type }
+end
+```
+
 ## Id
 
 The `id` property is declared via the DSL method of the same name, and takes a
@@ -92,6 +99,11 @@ Example:
 class SerializablePost < JSONAPI::Serializable::Resource
   # ...
   attribute :date  # This will have value @object.date
+```
+
+```ruby
+class SerializablePost < JSONAPI::Serializable::Resource
+  # ...
   attribute :date do
     @object.created_at
   end
@@ -111,13 +123,13 @@ class SerializablePost < JSONAPI::Serializable::Resource
   meta foo: 'bar'
 end
 ```
-or dynamically in a block:
+or dynamically in a block (in case it needs access to the exposures):
 
 ```ruby
 class SerializablePost < JSONAPI::Serializable::Resource
   # ...
   meta do
-    { foo: 'bar' }
+    { foo: @object.foo }
   end
 end
 ```
@@ -237,20 +249,11 @@ class SerializablePost < JSONAPI::Serializable::Resource
 end
 ```
 
+Note that while this usage is supported, it is actually recommended to set a
+global explicit mapping at the renderer level.
+
 ### Linkage data overriding
 
 Note: it is also possible to manually override the linkage data for a
 relationship (which can be useful to add linkage-level meta information) via the
 `linkage` DSL method.
-
-## Rails generators
-
-The jsonapi-rails gem comes with generators for serializable resource classes.
-It infers the attributes and relationships from your model definition.
-
-Usage:
-
-```
-$ bundle exec rails generate jsonapi:serializable Post
->   created  app/serializable/serializable_post.rb
-```
diff --git a/source/guides/serialization/index.html.md b/source/guides/serialization/index.html.md
index 6b875d4..c9cc5e0 100644
--- a/source/guides/serialization/index.html.md
+++ b/source/guides/serialization/index.html.md
@@ -5,8 +5,10 @@ layout: guides
 
 In order to build JSON API documents from your data, you need to define some
 *serializable resources*. Serializable resources encapsulate your domain objects
-(which can be any kind of objects) and present them in a suitable way for JSON
-API serialization. They are defined via an intuitive yet extensive DSL.
+(which can be any kind of objects -- `ActiveRecord`s, POROs, etc.) and present
+them in a suitable way for JSON API serialization. They are defined via an
+intuitive yet extensive DSL. In other libraries, serializable resources are
+usually called "serializers".
 
 Once your serializable resources are defined, you can pass your business objects
 to the *renderer*, that will build the appropriate serializable resources, and
diff --git a/source/guides/serialization/rendering.html.md b/source/guides/serialization/rendering.html.md
index aca9d48..af1e3e1 100644
--- a/source/guides/serialization/rendering.html.md
+++ b/source/guides/serialization/rendering.html.md
@@ -13,16 +13,16 @@ When using jsonapi-rb in plain ruby (or from within a framework outside of a
 controller), you can render a document as follows:
 
 ```ruby
-JSONAPI::Serializable::Renderer.render(posts)
+JSONAPI::Serializable::SuccessRenderer.render(posts)
 ```
 
 You can also pass options to the renderer:
 
 ```ruby
-JSONAPI::Serializable::Renderer.render(posts,
-                                       include: [:author, comments: [:author]],
-                                       fields:  { users: [:name, :email],
-                                                  posts: [:title, :content] })
+JSONAPI::Serializable::SuccessRenderer.render(posts,
+                                             include: [:author, comments: [:author]],
+                                             fields:  { users: [:name, :email],
+                                                        posts: [:title, :content] })
 ```
 
 For a comprehensive list of renderer options, see [Renderer options]().
@@ -52,9 +52,9 @@ When using jsonapi-rb with Hanami (via the jsonapi-hanami gem), enabling of
 jsonapi-rb features is opt-in, and is done by including
 `JSONAPI::Hanami::Action` in your actions.
 Rendering is done by setting options directly on the controller action instance.
-The primary data is set via the `self.body` setter.
+The primary data is set via the `self.data` setter.
 
-Exposures are available from within the SerializableResource class as instance
+Exposures are available from within the `SerializableResource` class as instance
 variables.
 
 Example:
@@ -96,13 +96,15 @@ The available options are:
   + `expose`: a hash of arbitrary variables that will be made available to the
     serializable resources as instance variables.
 + serializable resource class related options:
+  + `inferrer`: a hash globally mapping model class names to serializable resource
+    class names.
+  + `namespace`: the namespace in which to look for serializable resource
+    classes. This option can be specified as a constant (e.g. `V2`), or as a
+    string (e.g. `"V2"`).
   + `class`: the serializable resource class(es) to be used for the primary
     data. This option can be specified as a constant (e.g. `SerializablePost`),
     as a string (e.g. `"SerializablePost"`), or as a hash (e.g.
     `{ Article: "SerializableFormattedArticle", Letter: "SerializableFormattedLetter" }`).
-  + `namespace`: the namespace in which to look for serializable resource
-    classes. This option can be specified as a constant (e.g. `V2`), or as a
-    string (e.g. `"V2"`).
 + top level properties:
   + `links`: a set of top level links. This option can be specified as a hash.
   + `meta`: top level meta information. This option can be specified as a hash.
diff --git a/source/peeks/_plain.md b/source/peeks/_plain.md
index 3be681c..c7fa22f 100644
--- a/source/peeks/_plain.md
+++ b/source/peeks/_plain.md
@@ -5,22 +5,25 @@ gem 'jsonapi-rb'
 # Serialization
 require 'jsonapi/serializable'
 
-JSONAPI::Serializable::Renderer.render(posts,
-                                       expose: { url_helpers: MyUrlHelper.new },
-                                       include: [:author, comments: [:author]],
-                                       fields: { users: [:name, :email] })
+JSONAPI::Serializable::SuccessRenderer.render(
+  posts,
+  expose: { url_helpers: MyUrlHelper.new },
+  include: [:author, comments: [:author]],
+  fields: { users: [:name, :email] }
+)
 # => { data: [...], included: [...] }
 
 # Deserialization
 require 'jsonapi/deserializable'
 
-JSONAPI::Deserializable::Resource.call(json_hash)
+resource = JSONAPI::Deserializable::Resource.new(json_hash)
+resource.to_h
 # => {
 #      title: 'Welcome',
 #      date: '2016-11-17',
 #      author_id: '5',
 #      author_type: 'users',
-#      comment_ids: ['13', '29', '31'],
-#      comment_types: ['comments', 'comments', 'comments']
+#      comments_ids: ['13', '29', '31'],
+#      comments_types: ['comments', 'comments', 'comments']
 #    }
 ```
diff --git a/source/peeks/_serializable.md b/source/peeks/_serializable.md
index 07075db..22a669e 100644
--- a/source/peeks/_serializable.md
+++ b/source/peeks/_serializable.md
@@ -10,7 +10,7 @@ class SerializablePost < JSONAPI::Serializable::Resource
 
   belongs_to :author
 
-  has_many :comments, class: 'V2::SerializableComment' do
+  has_many :comments do
     data do
       @object.published_comments
     end
