Document unreachability handling of return NotImplemented (#20561)

There is a special case about unreachability, `return NotImplemented`,
which we did not until now mention, which we hereby now mention in the
documentation of `--warn-unreachable`.

I also add a test to test this claimed behavior thoroughly. The current
test tests its desired behavior, in a class, but the actual behavior of
mypy is much broader than that, and applies all the time, it seems.

Fixes #20462. That issue is not
correct anymore, as it was obsoleted by
#20488. However, during its
discussion @sterliakov brought up this `NotImplemented` edge case as
something that should be documented. I think the documentation after
this PR will be satisfactory by everyone's standards.

Similarly, this PR closes #20558.

Theoretically, there could be further special cases of unreachability of
which I am not aware, but these can be noted by later PRs if so.

Author: wyattscarpenter

docs/source/command_line.rst

@@ -537,13 +537,15 @@ potentially problematic or redundant in some way.
                 print(x + "bad")
 
     To help prevent mypy from generating spurious warnings, the "Statement is
-    unreachable" warning will be silenced in exactly two cases:
+    unreachable" warning will be silenced in exactly three cases:
 
     1.  When the unreachable statement is a ``raise`` statement, is an
         ``assert False`` statement, or calls a function that has the :py:data:`~typing.NoReturn`
         return type hint. In other words, when the unreachable statement
         throws an error or terminates the program in some way.
-    2.  When the unreachable statement was *intentionally* marked as unreachable
+    2.  When the unreachable statement is ``return NotImplemented``. This
+        is allowed by mypy due to its use in operator overloading.
+    3.  When the unreachable statement was *intentionally* marked as unreachable
         using :ref:`version_and_platform_checks`.
 
     .. note::

test-data/unit/check-unreachable-code.test

@@ -1639,6 +1639,20 @@ class C:
             return NotImplemented
 [builtins fixtures/isinstance.pyi]
 
+[case testIgnoreReturningNotImplementedSimple]
+# flags: --warn-unreachable
+-- This behavior may or may not actually be desirable.
+-- This test just serves to document mypy's current behavior.
+-- And mypy's handling of NotImplemented has long been known
+-- to be suboptimal, eg https://github.com/python/mypy/issues/363.
+-- If you change this behavior, please change the corresponding docs
+-- https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-warn-unreachable
+def foo() -> None:
+    return None
+    return NotImplemented #no error
+    return None # E: Statement is unreachable
+[builtins fixtures/isinstance.pyi]
+
 [case testPassAndEllipsisUnreachable]
 # flags: --warn-unreachable
 def f() -> None: