include a note about the importance of type coerce for custom ops

Change-Id: Ia7dab65523d6a34fcc92ee785ffe03f7e2a33cfd
(cherry picked from commit 56845d8cc2678c0aefd889a7fc711150661cd8e8)

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 1628987d3c45656ccdb3978c71ffa1195644dd29..65f46e43ff837533baa69cb562dd1779552075b0 100644 (file)
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -617,7 +617,7 @@ The above illustrates the SQL that's generated for an
 the ``||`` operator now compiles as MySQL's ``concat()`` function.
 
 If you have come across an operator which really isn't available, you can
-always use the :meth:`.ColumnOperators.op` method; this generates whatever operator you need:
+always use the :meth:`.Operators.op` method; this generates whatever operator you need:
 
 .. sourcecode:: pycon+sql
 
@@ -628,7 +628,17 @@ This function can also be used to make bitwise operators explicit. For example::
 
     somecolumn.op('&')(0xff)
 
-is a bitwise AND of the value in `somecolumn`.
+is a bitwise AND of the value in ``somecolumn``.
+
+When using :meth:`.Operators.op`, the return type of the expression may be important,
+especialy when the operator is used in an expression that will be sent as a result
+column.   For this case, be sure to make the type explicit, if not what's
+normally expected, using :func:`.type_coerce`::
+
+    from sqlalchemy import type_coerce
+    expr = type_coerce(somecolumn.op('-%>')('foo'), MySpecialType())
+    stmt = select([expr])
+
 
 Operator Customization
 ----------------------