more detail

docs/source/error_code_list.rst

@@ -1137,7 +1137,16 @@ Warn if multiple ``@overload`` variants overlap in unsafe ways.
     def takes_a(a: A) -> str:
         return foo(a)
 
-    assert isinstance(takes_a(B()), str)  # may fail when run
+    a: A = B()
+    value = takes_a(a)
+    # mypy will think that value is a str, but it could actually be an int
+    reveal_type(value) # Revealed type is "builtins.str"
+
+
+Note that in cases you ignore this error, mypy will usually still infer the
+types you expect.
+
+See :ref:`overloading <function-overloading> for more explanation.
 
 .. _code-annotation-unchecked:
 

docs/source/more_types.rst

@@ -501,7 +501,7 @@ To prevent these kinds of issues, mypy will detect and prohibit inherently unsaf
 overlapping overloads on a best-effort basis. Two variants are considered unsafely
 overlapping when both of the following are true:
 
-1. All of the arguments of the first variant are compatible with the second.
+1. All of the arguments of the first variant are potentially compatible with the second.
 2. The return type of the first variant is *not* compatible with (e.g. is not a
    subtype of) the second.
 
@@ -510,6 +510,9 @@ the ``object`` argument in the second, yet the ``int`` return type is not a subt
 ``str``. Both conditions are true, so mypy will correctly flag ``unsafe_func`` as
 being unsafe.
 
+Note that in cases you ignore the overlapping overload error, mypy will usually
+still infer the types you expect at callsites.
+
 However, mypy will not detect *all* unsafe uses of overloads. For example,
 suppose we modify the above snippet so it calls ``summarize`` instead of
 ``unsafe_func``: