From 1125b96594c1f201cfe3e6be74b99491c465ffde Mon Sep 17 00:00:00 2001
From: Jared Beck <jared@jaredbeck.com>
Date: Tue, 10 May 2016 02:11:41 -0400
Subject: [PATCH] Docs: re: where_object_changes

[ci skip]
---
 README.md                           | 10 ++++------
 lib/paper_trail/serializers/json.rb |  8 ++++----
 lib/paper_trail/serializers/yaml.rb |  8 ++++----
 lib/paper_trail/version_concern.rb  |  5 +++++
 4 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 0b816c183..6a7cd7bd8 100644
--- a/README.md
+++ b/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)
 ```
 
diff --git a/lib/paper_trail/serializers/json.rb b/lib/paper_trail/serializers/json.rb
index 612390797..d73a28db2 100644
--- a/lib/paper_trail/serializers/json.rb
+++ b/lib/paper_trail/serializers/json.rb
@@ -14,8 +14,8 @@ def dump(object)
         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 @@ def where_object_condition(arel_field, field, value)
         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
diff --git a/lib/paper_trail/serializers/yaml.rb b/lib/paper_trail/serializers/yaml.rb
index b449d1259..e054e969e 100644
--- a/lib/paper_trail/serializers/yaml.rb
+++ b/lib/paper_trail/serializers/yaml.rb
@@ -14,14 +14,14 @@ def dump(object)
         ::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
diff --git a/lib/paper_trail/version_concern.rb b/lib/paper_trail/version_concern.rb
index 4ab0bd4f3..2cb69e4cf 100644
--- a/lib/paper_trail/version_concern.rb
+++ b/lib/paper_trail/version_concern.rb
@@ -109,8 +109,10 @@ def timestamp_sort_order(direction = "asc")
         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 @@ def where_object(args = {})
         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)