Update docs for ActiveRecord `serialize`

For certain column types, using `serialize` is unnecessary, or the user
may get unexpected contents back from the DB adapter (which is handling
some basic deserialization for them). Call this out in the
documentation.

For background, see:

    https://gist.github.com/ernie/33f75f2294885b9806f9
    https://twitter.com/erniemiller/status/604262907442905090

1 files changed, 9 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/attribute_methods/serialization.rb b/activerecord/lib/active_record/attribute_methods/serialization.rb
index d0d8a968c5..216808b510 100644
--- a/activerecord/lib/active_record/attribute_methods/serialization.rb
+++ b/activerecord/lib/active_record/attribute_methods/serialization.rb
@@ -11,6 +11,15 @@ module ActiveRecord
         # serialized object must be of that class on assignment and retrieval.
         # Otherwise <tt>SerializationTypeMismatch</tt> will be raised.
         #
+        # Keep in mind that database adapters handle certain serialization tasks
+        # for you. For instance: +json+ and +sonb+ types in PostgreSQL will be
+        # converted between JSON object/array syntax and Ruby +Hash+ or +Array+
+        # objects transparently. There is no need to use +serialize+ in this
+        # case.
+        #
+        # For more complex cases, such as conversion to or from your application
+        # domain objects, consider using the ActiveRecord::Attributes API.
+        #
         # ==== Parameters
         #
         # * +attr_name+ - The field name that should be serialized.