Edits to discussion of unreachable code in the docs (python#8997)

JukkaL · web-flow · commit e50ba7e2c0c3 · 2020-06-19T11:41:47.000+01:00
Make it closer the style used elsewhere. It's also more concise now.
diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
@@ -809,40 +809,46 @@ not necessary:
         def test(self, t: List[int]) -> Sequence[str]:  # type: ignore[override]
             ...
 
-Unreachable code during typechecking
-------------------------------------
+Unreachable code
+----------------
 
-Sometimes a part of the code can become unreachable, even if not immediately obvious.
-It is important to note that in such cases, that part of the code will *not* be type-checked
-by mypy anymore. Consider the following code snippet:
+Mypy may consider some code as *unreachable*, even if it might not be
+immediately obvious why.  It's important to note that mypy will *not*
+type check such code. Consider this example:
 
 .. code-block:: python
 
     class Foo:
-        bar:str = ''
+        bar: str = ''
 
     def bar() -> None:
         foo: Foo = Foo()
         return
-        x:int = 'abc'
+        x: int = 'abc'  # Unreachable -- no error
 
-It is trivial to notice that any statement after ``return`` is unreachable and hence mypy will
-not complain about the mis-typed code below it. For a more subtle example, consider:
+It's easy to see that any statement after ``return`` is unreachable,
+and hence mypy will not complain about the mis-typed code below
+it. For a more subtle example, consider this code:
 
 .. code-block:: python
 
     class Foo:
-        bar:str = ''
+        bar: str = ''
 
     def bar() -> None:
         foo: Foo = Foo()
         assert foo.bar is None
-        x:int = 'abc'
+        x: int = 'abc'  # Unreachable -- no error
 
-Again, mypy will not throw any errors because the type of ``foo.bar`` says it's ``str`` and never ``None``.
-Hence the ``assert`` statement will always fail and the statement below will never be executed.
-Note that in Python, ``None`` is not a null-reference but an object of type ``NoneType``. This can
-also be demonstrated by the following:
+Again, mypy will not report any errors. The type of ``foo.bar`` is
+``str``, and mypy reasons that it can never be ``None``.  Hence the
+``assert`` statement will always fail and the statement below will
+never be executed.  (Note that in Python, ``None`` is not an empty
+reference but an object of type ``None``.)
+
+In this example mypy will go on to check the last line and report an
+error, since mypy thinks that the condition could be either True or
+False:
 
 .. code-block:: python
 
@@ -853,10 +859,7 @@ also be demonstrated by the following:
         foo: Foo = Foo()
         if not foo.bar:
             return
-        x:int = 'abc'
-
-Here mypy will go on to check the last line as well and report ``Incompatible types in assignment``.
+        x: int = 'abc'  # Reachable -- error
 
-If we want to let mypy warn us of such unreachable code blocks, we can use the ``--warn-unreachable``
-option. With this mypy will throw ``Statement is unreachable`` error along with the line number from
-where the unreachable block starts.
+If you use the :option:`--warn-unreachable <mypy --warn-unreachable>` flag, mypy will generate
+an error about each unreachable code block.
