Docs: re: where_object_changes

[ci skip]

README.md

@@ -226,13 +226,11 @@ version.index
 # Returns the event that caused this version (create|update|destroy).
 version.event
 
-# Query versions objects by attributes.
+# Query the `versions.object` column (or `object_changes` column), by
+# attributes, using the SQL LIKE operator. Known issue: inconsistent results for
+# numeric values due to limitations of SQL wildcard matchers against the
+# serialized objects.
 PaperTrail::Version.where_object(attr1: val1, attr2: val2)
-
-# Query versions object_changes field by attributes (requires
-# `object_changes` column on versions table).
-# Also can't guarantee consistent query results for numeric values
-# due to limitations of SQL wildcard matchers against the serialized objects.
 PaperTrail::Version.where_object_changes(attr1: val1)
 ```
 

lib/paper_trail/serializers/json.rb

@@ -14,8 +14,8 @@ module PaperTrail
         ActiveSupport::JSON.encode object
       end
 
-      # Returns a SQL condition to be used to match the given field and value
-      # in the serialized object
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized object.
       def where_object_condition(arel_field, field, value)
         # Convert to JSON to handle strings and nulls correctly.
         json_value = value.to_json
@@ -32,8 +32,8 @@ module PaperTrail
         end
       end
 
-      # Returns a SQL condition to be used to match the given field and value
-      # in the serialized object_changes
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized `object_changes`.
       def where_object_changes_condition(arel_field, field, value)
         # Convert to JSON to handle strings and nulls correctly.
         json_value = value.to_json

lib/paper_trail/serializers/yaml.rb

@@ -14,14 +14,14 @@ module PaperTrail
         ::YAML.dump object
       end
 
-      # Returns a SQL condition to be used to match the given field and value
-      # in the serialized object
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized object.
       def where_object_condition(arel_field, field, value)
         arel_field.matches("%\n#{field}: #{value}\n%")
       end
 
-      # Returns a SQL condition to be used to match the given field and value
-      # in the serialized object_changes
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized `object_changes`.
       def where_object_changes_condition(arel_field, field, value)
         # Need to check first (before) and secondary (after) fields
         m1 = nil

lib/paper_trail/version_concern.rb

@@ -109,8 +109,10 @@ module PaperTrail
         end
       end
 
+      # Query the `versions.objects` column using the SQL LIKE operator.
       # Performs an attribute search on the serialized object by invoking the
       # identically-named method in the serializer being used.
+      # @api public
       def where_object(args = {})
         raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
 
@@ -135,6 +137,9 @@ module PaperTrail
         end
       end
 
+      # Query the `versions.object_changes` column by attributes, using the
+      # SQL LIKE operator.
+      # @api public
       def where_object_changes(args = {})
         raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)