PEP 387: Use the @deprecated decorator if possible (#3525)

PEP 702 says that the deprecation policy should be updated to
encourage use of @deprecated for deprecations.

peps/pep-0387.rst

@@ -160,6 +160,10 @@ several releases:
    coexist for many releases [#warnings]_.  The warning message should
    include the release the incompatibility is expected to become the
    default and a link to an issue that users can post feedback to.
+   When feasible, also change `typeshed <https://github.com/python/typeshed>`_
+   to add the ``@deprecated`` decorator (see :pep:`702`) to the deprecated API,
+   so that users of static type checkers have another way to learn
+   about the deprecation.
 
    For C API, a compiler warning generated by the ``Py_DEPRECATED`` macro
    is also acceptable.