Document unreachability handling of return NotImplemented

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: