Various documentation updates (mostly about error codes) (#12680)

JukkaL · JukkaL · commit 48957aa91634 · 2022-04-27T15:03:12.000+01:00
Document some additional error codes and some general doc updates for
the 0.950 release.
diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
@@ -616,27 +616,29 @@ of the above sections.
 .. option:: --disable-error-code
 
     This flag allows disabling one or multiple error codes globally.
+    See :ref:`error-codes` for more information.
 
     .. code-block:: python
 
         # no flag
         x = 'a string'
         x.trim()  # error: "str" has no attribute "trim"  [attr-defined]
 
-        # --disable-error-code attr-defined
+        # When using --disable-error-code attr-defined
         x = 'a string'
         x.trim()
 
 .. option:: --enable-error-code
 
     This flag allows enabling one or multiple error codes globally.
+    See :ref:`error-codes` for more information.
 
-    Note: This flag will override disabled error codes from the --disable-error-code
-    flag
+    Note: This flag will override disabled error codes from the
+    :option:`--disable-error-code <mypy --disable-error-code>` flag.
 
     .. code-block:: python
 
-        # --disable-error-code attr-defined
+        # When using --disable-error-code attr-defined
         x = 'a string'
         x.trim()
 
diff --git a/docs/source/error_code_list.rst b/docs/source/error_code_list.rst
@@ -679,6 +679,43 @@ implementation.
    def func(value):
        pass  # actual implementation
 
+Check that coroutine return value is used [unused-coroutine]
+------------------------------------------------------------
+
+Mypy ensures that return values of async def functions are not
+ignored, as this is usually a programming error, as the coroutine
+won't be executed at the call site.
+
+.. code-block:: python
+
+   async def f() -> None:
+       ...
+
+   async def g() -> None:
+       f()  # Error: missing await
+       await f()  # OK
+
+You can work around this error by assigning the result to a temporary,
+otherwise unused variable:
+
+.. code-block:: python
+
+       _ = f()  # No error
+
+Check types in assert_type [assert-type]
+----------------------------------------
+
+The inferred type for an expression passed to ``assert_type`` must match
+the provided type.
+
+.. code-block:: python
+
+   from typing_extensions import assert_type
+
+   assert_type([1], list[int])  # OK
+
+   assert_type([1], list[str])  # Error
+
 Report syntax errors [syntax]
 -----------------------------
 
diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst
@@ -200,7 +200,7 @@ mypy generates an error if it thinks that an expression is redundant.
 
 .. code-block:: python
 
-    # mypy: enable-error-code redundant-expr
+    # Use "mypy --enable-error-code redundant-expr ..."
 
     def example(x: int) -> None:
         # Error: Left operand of "and" is always true  [redundant-expr]
@@ -222,7 +222,7 @@ since unless implemented by a sub-type, the expression will always evaluate to t
 
 .. code-block:: python
 
-    # mypy: enable-error-code truthy-bool
+    # Use "mypy --enable-error-code truthy-bool ..."
 
     class Foo:
       pass
@@ -237,7 +237,8 @@ This check might falsely imply an error. For example, ``Iterable`` does not impl
 
 .. code-block:: python
 
-    # mypy: enable-error-code truthy-bool
+    # Use "mypy -enable-error-code truthy-bool ..."
+
     from typing import Iterable
 
     def transform(items: Iterable[int]) -> Iterable[int]:
@@ -270,7 +271,7 @@ Example:
 
 .. code-block:: python
 
-    # mypy: enable-error-code ignore-without-code
+    # Use "mypy --enable-error-code ignore-without-code ..."
 
     class Foo:
         def __init__(self, name: str) -> None:
@@ -288,3 +289,32 @@ Example:
     # This line warns correctly about the typo in the attribute name
     # Error: "Foo" has no attribute "nme"; maybe "name"?
     f.nme = 42  # type: ignore[assignment]
+
+Check that awaitable return value is used [unused-awaitable]
+------------------------------------------------------------
+
+If you use :option:`--enable-error-code unused-awaitable <mypy --enable-error-code>`,
+mypy generates an error if you don't use a returned value that defines ``__await__``.
+
+Example:
+
+.. code-block:: python
+
+    # Use "mypy --enable-error-code unused-awaitable ..."
+
+    import asyncio
+
+    async def f() -> int: ...
+
+    async def g() -> None:
+        # Error: Value of type "Task[int]" must be used
+        #        Are you missing an await?
+        asyncio.create_task(f())
+
+You can assign the value to a temporary, otherwise unused to variable to
+silence the error:
+
+.. code-block:: python
+
+    async def g() -> None:
+        _ = asyncio.create_task(f())  # No error
diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst
@@ -24,7 +24,7 @@ Displaying error codes
 ----------------------
 
 Error codes are not displayed by default.  Use :option:`--show-error-codes <mypy --show-error-codes>`
-or config `show_error_codes = True` to display error codes. Error codes are shown inside square brackets:
+or config ``show_error_codes = True`` to display error codes. Error codes are shown inside square brackets:
 
 .. code-block:: text
 
@@ -46,11 +46,8 @@ line.  This can be used even if you have not configured mypy to show
 error codes. Currently it's only possible to disable arbitrary error
 codes on individual lines using this comment.
 
-.. note::
-
-  There are command-line flags and config file settings for enabling
-  certain optional error codes, such as :option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>`,
-  which enables the ``no-untyped-def`` error code.
+You can also use :option:`--disable-error-code <mypy --disable-error-code>`
+to disable specific error codes globally.
 
 This example shows how to ignore an error about an imported name mypy
 thinks is undefined:
@@ -60,3 +57,15 @@ thinks is undefined:
    # 'foo' is defined in 'foolib', even though mypy can't see the
    # definition.
    from foolib import foo  # type: ignore[attr-defined]
+
+
+Enabling specific error codes
+-----------------------------
+
+There are command-line flags and config file settings for enabling
+certain optional error codes, such as :option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>`,
+which enables the ``no-untyped-def`` error code.
+
+You can use :option:`--enable-error-code <mypy --enable-error-code>` to
+enable specific error codes that don't have a dedicated command-line
+flag or config file setting.
diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst
@@ -25,6 +25,14 @@ you can create such packages.
    :pep:`561` specifies how a package can declare that it supports
    type checking.
 
+.. note::
+
+   New versions of stub packages often use type system features not
+   supported by older, and even fairly recent mypy versions. If you
+   pin to an older version of mypy (using ``requirements.txt``, for
+   example), it is recommended that you also pin the versions of all
+   your stub package dependencies.
+
 Using installed packages with mypy (PEP 561)
 ********************************************
 
