Update documentation on --warn-no-return and NoReturn (#2920)

Fixes #2919.
Fixes #2918.

docs/source/command_line.rst

@@ -365,6 +365,7 @@ Here are some more useful flags:
   for functions with ``None`` or ``Any`` return types. Mypy
   also currently ignores functions with an empty body or a body that is
   just ellipsis (``...``), since these can be valid as abstract methods.
+  This option is on by default.
 
 - ``--warn-return-any`` causes mypy to generate a warning when returning a value
   with type ``Any`` from a function declared with a non- ``Any`` return type.

docs/source/config_file.rst

@@ -165,7 +165,7 @@ overridden by the pattern sections matching the module name.
 - ``ignore_errors`` (Boolean, default False) ignores all non-fatal
   errors.
 
-- ``warn_no_return`` (Boolean, default False) shows errors for
+- ``warn_no_return`` (Boolean, default True) shows errors for
   missing return statements on some execution paths.
 
 - ``warn_return_any`` (Boolean, default False) shows a warning when

docs/source/kinds_of_types.rst

@@ -356,6 +356,35 @@ check against ``None`` in the if condition.
 
     ``--strict-optional`` is experimental and still has known issues.
 
+.. _noreturn:
+
+The NoReturn type
+*****************
+
+Mypy provides support for functions that never return. For
+example, a function that unconditionally raises an exception:
+
+.. code-block:: python
+
+   from mypy_extensions import NoReturn
+
+   def stop() -> NoReturn:
+       raise Exception('no way')
+
+Mypy will ensure that functions annotated as returning ``NoReturn``
+truly never return, either implicitly or explicitly. Mypy will also
+recognize that the code after calls to such functions is unreachable
+and will behave accordingly:
+
+.. code-block:: python
+
+   def f(x: int) -> int:
+       if x == 0:
+           return x
+       stop()
+       return 'whatever works'  # No error in an unreachable block
+
+
 Class name forward references
 *****************************