Document Serializer settings and private api

Author: bf4

docs/general/serializers.md

@@ -0,0 +1,149 @@
+# Serializers
+
+## About
+
+ActiveModelSerializers works through two components: **serializers** and **adapters**.
+
+Serializers describe _which_ attributes and relationships should be serialized.
+
+```ruby
+serializer = SomeSerializer.new(resource, serializer_options)
+serializer.attributes
+serializer.associations
+```
+
+Adapters describe _how_ attributes and relationships should be serialized.
+
+```ruby
+adapter = Adapter.create(serializer, adapter_options)
+adapter.to_json
+adapter.as_json
+adapter.serializable_hash
+```
+
+SerializableResource co-ordinates the resource, Adapter and Serializer to produce the
+resource serialization, which has the `#as_json`, `#to_json` and `#serializable_hash`
+methods used by the Rails JSON Renderer.
+
+```ruby
+serialization = SerializableResource.new(resource, options)
+serialization.to_json
+serialization.as_json
+serialization.serializable_hash
+```
+
+See [ARCHITECTURE.md](../ARCHITECTURE.md) for more information.
+
+## Usage
+
+Given a serializer class:
+
+```ruby
+class SomeSerializer < ActiveModel::Serializer
+end
+```
+
+The following methods may be defined in it:
+
+### Attributes
+
+#### ::attributes
+
+Serialization of the resource `title` and `body`
+
+| `attributes :title, :body` | `{ title: 'Some Title', body: 'Some Body' }` |
+| `attributes :title, :body`<br>`def body "Special #{object.body}" end` | `{ title: 'Some Title', body: 'Special Some Body' }` |
+
+
+#### ::attribute
+
+Serialization of the resource `title`
+
+| `attribute :title` | { title: 'Some Title' } `
+| `attribute :title, key: :name` | { name: 'Some Title' } `
+| `attribute :title { 'A Different Title'}` | { title: 'A Different Title' } `
+| `attribute :title`<br>`def title 'A Different Title' end` | { title: 'A Different Title' } `
+
+
+### Associations
+
+#### ::has_one
+
+e.g.
+
+```ruby
+has_one :bio
+has_one :blog, key: :site
+has_one :maker, virtual_value: { id: 1 }
+```
+
+#### ::has_many
+
+e.g.
+
+```ruby
+has_many :comments
+has_many :comments, key: :reviews
+has_many :comments, serializer: CommentPreviewSerializer
+has_many :reviews, virtual_value: [{ id: 1 }, { id: 2 }]
+has_many :comments, key: :last_comments do
+  last(1)
+end
+```
+
+#### ::belongs_to
+
+e.g.
+
+```ruby
+belongs_to :author, serializer: AuthorPreviewSerializer
+belongs_to :author, key: :writer
+belongs_to :post
+belongs_to :blog
+def blog
+  Blog.new(id: 999, name: 'Custom blog')
+end
+```
+
+### Caching
+
+#### ::cache
+
+e.g.
+
+```ruby
+cache key: 'post', expires_in: 0.1, skip_digest: true
+cache expires_in: 1.day, skip_digest: true
+cache key: 'writer', skip_digest: true
+cache only: [:name], skip_digest: true
+cache except: [:content], skip_digest: true
+cache key: 'blog'
+cache only: [:id]
+```
+
+#### #cache_key
+
+e.g.
+
+```ruby
+# Uses a custom non-time-based cache key
+def cache_key
+  "#{self.class.name.downcase}/#{self.id}"
+end
+```
+
+### Other
+
+### ::type
+
+e.g.
+
+```ruby
+class UserProfileSerializer < ActiveModel::Serializer
+  type 'profile'
+end
+```
+
+### ::link
+
+For more information, see [the Serializer class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer.rb)

lib/active_model/serializer/attributes.rb

@@ -1,6 +1,7 @@
 module ActiveModel
   class Serializer
     module Attributes
+      # @api private
       class Attribute
         delegate :call, to: :reader
 
@@ -19,12 +20,14 @@ def self.build(name, block)
           end
         end
       end
+      # @api private
       class AttributeReader < Attribute
         def initialize(name)
           super(name)
           @reader = ->(instance) { instance.read_attribute_for_serialization(name) }
         end
       end
+      # @api private
       class AttributeBlock < Attribute
         def initialize(name, block)
           super(name)

lib/active_model/serializer/reflection.rb

@@ -35,10 +35,12 @@ def initialize(*)
         @reader = self.class.build_reader(name, block)
       end
 
+      # @api private
       def value(instance)
         call(instance)
       end
 
+      # @api private
       def self.build_reader(name, block)
         if block
           ->(instance) { instance.read_attribute_for_serialization(name).instance_eval(&block) }