From 30528cda9e30e42915f3a0fa204d822ce013c168 Mon Sep 17 00:00:00 2001 From: bogdanvlviv Date: Sat, 17 Feb 2018 00:41:54 +0200 Subject: [PATCH] Fix docs of ActiveJob custom argument serializers Add `:nodoc:` to `ActiveJob::Serializers` Add `:doc:` to `ActiveJob::Serializers::ObjectSerializer#klass` Express `ActiveJob::Serializers::ObjectSerializer#klass` as private method --- activejob/lib/active_job/serializers.rb | 12 +++---- .../serializers/object_serializer.rb | 36 +++++++++---------- guides/source/active_job_basics.md | 27 +++++++------- 3 files changed, 37 insertions(+), 38 deletions(-) diff --git a/activejob/lib/active_job/serializers.rb b/activejob/lib/active_job/serializers.rb index 7ee63a8a87..ec223440e3 100644 --- a/activejob/lib/active_job/serializers.rb +++ b/activejob/lib/active_job/serializers.rb @@ -4,8 +4,8 @@ require "set" module ActiveJob # The ActiveJob::Serializers module is used to store a list of known serializers - # and to add new ones. It also has helpers to serialize/deserialize objects - module Serializers + # and to add new ones. It also has helpers to serialize/deserialize objects. + module Serializers # :nodoc: extend ActiveSupport::Autoload extend ActiveSupport::Concern @@ -23,7 +23,7 @@ module ActiveJob class << self # Returns serialized representative of the passed object. # Will look up through all known serializers. - # Raises `ActiveJob::SerializationError` if it can't find a proper serializer. + # Raises ActiveJob::SerializationError if it can't find a proper serializer. def serialize(argument) serializer = serializers.detect { |s| s.serialize?(argument) } raise SerializationError.new("Unsupported argument type: #{argument.class.name}") unless serializer @@ -32,7 +32,7 @@ module ActiveJob # Returns deserialized object. # Will look up through all known serializers. - # If no serializers found will raise `ArgumentError` + # If no serializer found will raise ArgumentError. def deserialize(argument) serializer_name = argument[Arguments::OBJECT_SERIALIZER_KEY] raise ArgumentError, "Serializer name is not present in the argument: #{argument.inspect}" unless serializer_name @@ -43,12 +43,12 @@ module ActiveJob serializer.deserialize(argument) end - # Returns list of known serializers + # Returns list of known serializers. def serializers self._additional_serializers end - # Adds a new serializer to a list of known serializers + # Adds new serializers to a list of known serializers. def add_serializers(*new_serializers) self._additional_serializers += new_serializers.flatten end diff --git a/activejob/lib/active_job/serializers/object_serializer.rb b/activejob/lib/active_job/serializers/object_serializer.rb index 9f59e8236f..1dfd1e44be 100644 --- a/activejob/lib/active_job/serializers/object_serializer.rb +++ b/activejob/lib/active_job/serializers/object_serializer.rb @@ -2,25 +2,25 @@ module ActiveJob module Serializers - # Base class for serializing and deserializing custom times. + # Base class for serializing and deserializing custom objects. # - # Example + # 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 + # class MoneySerializer < ActiveJob::Serializers::ObjectSerializer + # def serialize(money) + # super("amount" => money.amount, "currency" => money.currency) # end + # + # def deserialize(hash) + # Money.new(hash["amount"], hash["currency"]) + # end + # + # private + # + # def klass + # Money + # end + # end class ObjectSerializer include Singleton @@ -43,10 +43,10 @@ module ActiveJob raise NotImplementedError end - protected + private # The class of the object that will be serialized. - def klass + def klass # :doc: raise NotImplementedError end end diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index 9b738e8cdd..6db7ce370f 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -346,12 +346,12 @@ ActiveJob supports the following types of arguments by default: - Basic types (`NilClass`, `String`, `Integer`, `Fixnum`, `Bignum`, `Float`, `BigDecimal`, `TrueClass`, `FalseClass`) - `Symbol` - - `ActiveSupport::Duration` - `Date` - `Time` - `DateTime` - `ActiveSupport::TimeWithZone` - - `Hash`. Keys should be of `String` or `Symbol` type + - `ActiveSupport::Duration` + - `Hash` (Keys should be of `String` or `Symbol` type) - `ActiveSupport::HashWithIndifferentAccess` - `Array` @@ -385,39 +385,38 @@ 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. +You can extend the list of supported argument types. You just need to define your own serializer: ```ruby class MoneySerializer < ActiveJob::Serializers::ObjectSerializer - # Check if this object should be serialized using this serializer. + # Checks if an argument should be serialized by this serializer. def serialize?(argument) argument.is_a? Money end - # Convert an object to a simpler representative using supported object types. + # Converts 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. - # You should call `super` to add the custom serializer type to the hash - def serialize(object) + # You should call `super` to add the custom serializer type to the hash. + def serialize(money) super( - "cents" => object.cents, - "currency" => object.currency + "amount" => money.amount, + "currency" => money.currency ) end - # Convert serialized value into a proper object + # Converts serialized value into a proper object. def deserialize(hash) - Money.new hash["cents"], hash["currency"] + Money.new(hash["amount"], hash["currency"]) end end ``` -And now you just need to add this serializer to a list: +and add this serializer to the list: ```ruby -Rails.application.config.active_job.custom_serializers << MySpecialSerializer +Rails.application.config.active_job.custom_serializers << MoneySerializer ``` - Exceptions ----------