Improve documentation on custom serializers

3 files changed, 26 insertions, 57 deletions

diff --git a/activejob/README.md b/activejob/README.md
index 56562d870b..f1ebb76e08 100644
--- a/activejob/README.md
+++ b/activejob/README.md
@@ -52,17 +52,8 @@ MyJob.set(wait: 1.week).perform_later(record) # Enqueue a job to be performed 1
 
 That's it!
 
-## Supported types for arguments
 
-ActiveJob supports the following types of arguments by default:
-
-  - Standard types (`NilClass`, `String`, `Integer`, `Fixnum`, `Bignum`, `Float`, `BigDecimal`, `TrueClass`, `FalseClass`)
-  - `Hash`. Keys should be of `String` or `Symbol` type
-  - `ActiveSupport::HashWithIndifferentAccess`
-  - `Array`
-
-
-### GlobalID support
+## GlobalID support
 
 Active Job supports [GlobalID serialization](https://github.com/rails/globalid/) for parameters. This makes it possible
 to pass live Active Record objects to your job instead of class/id pairs, which
@@ -90,53 +81,6 @@ end
 This works with any class that mixes in GlobalID::Identification, which
 by default has been mixed into Active Record classes.
 
-### Serializers
-
-You can extend list of supported types for arguments. You just need to define your own serializer.
-
-```ruby
-class MySpecialSerializer
-  class << self
-    # Check if this object should be serialized using this serializer
-    def serialize?(argument)
-      object.is_a? MySpecialValueObject
-    end
-
-    # Convert an object to a simpler representative using supported object types.
-    # The recommended representative is a Hash with a specific key. Keys can be of basic types only
-    def serialize(object)
-      {
-        key => ActiveJob::Serializers.serialize(object.value)
-        'another_attribute' => ActiveJob::Serializers.serialize(object.another_attribute)
-      }
-    end
-
-    # Check if this serialized value be deserialized using this serializer
-    def deserialize?(argument)
-      object.is_a?(Hash) && object.keys == [key, 'another_attribute']
-    end
-
-    # Convert serialized value into a proper object
-    def deserialize(object)
-      value = ActiveJob::Serializers.deserialize(object[key])
-      another_attribute = ActiveJob::Serializers.deserialize(object['another_attribute'])
-      MySpecialValueObject.new value, another_attribute
-    end
-
-    # Define this method if you are using a hash as a representative.
-    # This key will be added to a list of restricted keys for hashes. Use basic types only
-    def key
-      "_aj_custom_dummy_value_object"
-    end
-  end
-end
-```
-
-And now you just need to add this serializer to a list:
-
-```ruby
-ActiveJob::Base.add_serializers(MySpecialSerializer)
-```
 
 ## Supported queueing systems
 
diff --git a/activejob/lib/active_job/serializers/base_serializer.rb b/activejob/lib/active_job/serializers/base_serializer.rb
index 2e510781cf..155eeb29c3 100644
--- a/activejob/lib/active_job/serializers/base_serializer.rb
+++ b/activejob/lib/active_job/serializers/base_serializer.rb
@@ -2,6 +2,7 @@
 
 module ActiveJob
   module Serializers
+    # Implement the basic interface for Active Job arguments serializers.
     class BaseSerializer
       include Singleton
 
@@ -9,24 +10,29 @@ module ActiveJob
         delegate :serialize?, :deserialize?, :serialize, :deserialize, to: :instance
       end
 
+      # Determines if an argument should be serialized by a serializer.
       def serialize?(argument)
         argument.is_a?(klass)
       end
 
+      # Determines if an argument should be deserialized by a serializer.
       def deserialize?(_argument)
         raise NotImplementedError
       end
 
+      # Serializes an argument to a JSON primitive type.
       def serialize(_argument)
         raise NotImplementedError
       end
 
+      # Deserilizes an argument form a JSON primiteve type.
       def deserialize(_argument)
         raise NotImplementedError
       end
 
       protected
 
+        # The class of the object that will be serialized.
         def klass
           raise NotImplementedError
         end
diff --git a/activejob/lib/active_job/serializers/object_serializer.rb b/activejob/lib/active_job/serializers/object_serializer.rb
index 318eabebdf..940b6ff95d 100644
--- a/activejob/lib/active_job/serializers/object_serializer.rb
+++ b/activejob/lib/active_job/serializers/object_serializer.rb
@@ -2,6 +2,25 @@
 
 module ActiveJob
   module Serializers
+    # Base class for serializing and deserializing custom times.
+    #
+    # Example
+    #
+    #     class MoneySerializer < ActiveJob::Serializers::ObjectSerializer
+    #       def serialize(money)
+    #         super("cents" => money.cents, "currency" => money.currency)
+    #       end
+    #
+    #       def deserialize(hash)
+    #         Money.new(hash["cents"], hash["currency"])
+    #       end
+    #
+    #       private
+    #
+    #         def klass
+    #           Money
+    #         end
+    #     end
     class ObjectSerializer < BaseSerializer
       def serialize(hash)
         { OBJECT_SERIALIZER_KEY => self.class.name }.merge!(hash)