Rewrite the section on fused types in function signatures to make it clearer how multiple fused types interact here.

1 files changed, 27 insertions, 11 deletions

diff --git a/docs/src/userguide/fusedtypes.rst b/docs/src/userguide/fusedtypes.rst
index b108b944e..1ca18daf6 100644
--- a/docs/src/userguide/fusedtypes.rst
+++ b/docs/src/userguide/fusedtypes.rst
@@ -63,24 +63,40 @@ Fused types can be used to declare parameters of functions or methods::
     cdef cfunc(my_fused_type arg):
         return arg + 1
 
-If the you use the same fused type more than once in an argument list, then each
-specialization of the fused type must be the same::
+If the same fused type appears more than once in the function arguments,
+then they will all have the same specialised type::
 
     cdef cfunc(my_fused_type arg1, my_fused_type arg2):
-        return cython.typeof(arg1) == cython.typeof(arg2)
+        # arg1 and arg2 always have the same type here
+        return arg1 + arg2
 
-In this case, the type of both parameters is either an int, or a double
-(according to the previous examples). However, because these arguments use the
-same fused type ``my_fused_type``, both ``arg1`` and ``arg2`` are
-specialized to the same type.  Therefore this function returns True for every
-possible valid invocation. You are allowed to mix fused types however::
+Here, the type of both parameters is either an int, or a double
+(according to the previous examples), because they use the same fused type
+name ``my_fused_type``.  Mixing different fused types (or differently named
+fused types) in the arguments will specialise them independently::
 
     def func(A x, B y):
         ...
 
-where ``A`` and ``B`` are different fused types.  This will result in
-specialized code paths for all combinations of types contained in ``A``
-and ``B``.
+This will result in specialized code paths for all combinations of types
+contained in ``A`` and ``B``, e.g.::
+
+    ctypedef fused my_fused_type:
+        cython.int
+        cython.double
+
+    ctypedef fused my_fused_type2:
+        cython.int
+        cython.double
+
+    cdef func(my_fused_type a, my_fused_type2 b):
+        # a and b may have the same or different types here
+        print("SAME!" if my_fused_type is my_fused_type2 else "NOT SAME!)
+        return a + b
+
+Note that a simple typedef to rename the fused type does not currently work here.
+See Github issue :issue:`4302`.
+
 
 Fused types and arrays
 ----------------------