From a11cb91a8a67f7a651b0ab2bb60353f95077eb9e Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 1 Aug 2018 13:37:52 -0400
Subject: [PATCH] Fix documentation for compare_against_backend SQLAlchemy
 method

Change-Id: Ic25de4facdb5467075f0f8b7e028e3e7db67ab66
Fixes: #501
---
 docs/build/autogenerate.rst | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst
index a15a7f9c..b0f73d5c 100644
--- a/docs/build/autogenerate.rst
+++ b/docs/build/autogenerate.rst
@@ -409,9 +409,10 @@ are being used::
 
     def my_compare_type(context, inspected_column,
                 metadata_column, inspected_type, metadata_type):
-        # return True if the types are different,
-        # False if not, or None to allow the default implementation
-        # to compare these types
+        # return False if the metadata_type is the same as the inspected_type
+        # or None to allow the default implementation to compare these
+        # types. a return value of True means the two types do not
+        # match and should result in a type change operation.
         return None
 
     context.configure(
@@ -439,14 +440,27 @@ will proceed::
         # ...
 
         def compare_against_backend(self, dialect, conn_type):
-            # return True if the types are different,
-            # False if not, or None to allow the default implementation
-            # to compare these types
+            # return True if this type is the same as the given database type,
+            # or None to allow the default implementation to compare these
+            # types. a return value of False means the given type does not
+            # match this type.
+
             if dialect.name == 'postgresql':
                 return isinstance(conn_type, postgresql.UUID)
             else:
                 return isinstance(conn_type, String)
 
+.. warning::
+
+    The boolean return values for the above
+    ``compare_against_backend`` method, which is part of SQLAlchemy and not
+    Alembic,are **the opposite** of that of the
+    :paramref:`.EnvironmentContext.configure.compare_type` callable, returning
+    ``True`` for types that are the same vs. ``False`` for types that are
+    different.The :paramref:`.EnvironmentContext.configure.compare_type`
+    callable on the other hand should return ``True`` for types that are
+    **different**.
+
 The order of precedence regarding the
 :paramref:`.EnvironmentContext.configure.compare_type` callable vs. the
 type itself implementing ``compare_against_backend`` is that the
-- 
2.47.2