[3.6] bpo-31567: add or fix decorator markup in docs (GH-3959) (GH-3966)

(cherry picked from commit 0e61e67a57deb4abc677808201d7cf3c38138e02)

diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 6001db32df49c3b7dba692db63cb66c9457c8347..9522dd62049138b5e809e61e0f16c7f7f3a7554c 100644 (file)
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -278,7 +278,7 @@ The :mod:`abc` module also provides the following decorators:
        :func:`abstractmethod`, making this decorator redundant.
 
 
-.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
+.. decorator:: abstractproperty
 
    A subclass of the built-in :func:`property`, indicating an abstract
    property.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index bd4c94fcae19af881efe0b835eccc06d7359f894..7a7a84d1d424dff6b89b8999607e2df6c078eff6 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -182,9 +182,9 @@ are always available.  They are listed here in alphabetical order.
    base 16).  :exc:`ValueError` will be raised if *i* is outside that range.
 
 
-.. function:: classmethod(function)
+.. decorator:: classmethod
 
-   Return a class method for *function*.
+   Transform a method into a class method.
 
    A class method receives the class as implicit first argument, just like an
    instance method receives the instance. To declare a class method, use this
@@ -1384,9 +1384,9 @@ are always available.  They are listed here in alphabetical order.
 
    For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
 
-.. function:: staticmethod(function)
+.. decorator:: staticmethod
 
-   Return a static method for *function*.
+   Transform a method into a static method.
 
    A static method does not receive an implicit first argument. To declare a static
    method, use this idiom::
@@ -1405,12 +1405,21 @@ are always available.  They are listed here in alphabetical order.
    :func:`classmethod` for a variant that is useful for creating alternate class
    constructors.
 
+   Like all decorators, it is also possible to call ``staticmethod`` as
+   a regular function and do something with its result.  This is needed
+   in some cases where you need a reference to a function from a class
+   body and you want to avoid the automatic transformation to instance
+   method.  For these cases, use this idiom:
+
+      class C:
+          builtin_open = staticmethod(open)
+
    For more information on static methods, consult the documentation on the
    standard type hierarchy in :ref:`types`.
 
-   .. index::
-      single: string; str() (built-in function)
 
+.. index::
+   single: string; str() (built-in function)
 
 .. _func-str:
 .. class:: str(object='')

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 9a8defee546bf3a9b3084ed736e4c83dc3a6833d..28062c11890ed10304a4ede90a0a1452180dda11 100644 (file)
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -264,9 +264,9 @@ The :mod:`functools` module defines the following functions:
           return value
 
 
-.. decorator:: singledispatch(default)
+.. decorator:: singledispatch
 
-   Transforms a function into a :term:`single-dispatch <single
+   Transform a function into a :term:`single-dispatch <single
    dispatch>` :term:`generic function`.
 
    To define a generic function, decorate it with the ``@singledispatch``

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 9d4ff7ad8b45a3830ba1e319455e230ba7022205..1a3f8f9c5dce1c106e876f3fb19e6e5ca68de6ae 100644 (file)
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -440,7 +440,7 @@ The :mod:`test.support` module defines the following functions:
    otherwise.
 
 
-.. decorator:: skip_unless_symlink()
+.. decorator:: skip_unless_symlink
 
    A decorator for running tests that require support for symbolic links.
 

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index bd04f731a1238bdb6553bfc54782d0f5db99b5cc..9883d8bbe8659606e0224b79b33b0f73562c2dcd 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -897,17 +897,17 @@ The module defines the following classes, functions and decorators:
 
    See :pep:`484` for details and comparison with other typing semantics.
 
-.. decorator:: no_type_check(arg)
+.. decorator:: no_type_check
 
    Decorator to indicate that annotations are not type hints.
 
-   The argument must be a class or function; if it is a class, it
+   This works as class or function :term:`decorator`.  With a class, it
    applies recursively to all methods defined in that class (but not
    to methods defined in its superclasses or subclasses).
 
    This mutates the function(s) in place.
 
-.. decorator:: no_type_check_decorator(decorator)
+.. decorator:: no_type_check_decorator
 
    Decorator to give another decorator the :func:`no_type_check` effect.
 

diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py
index a3b2ea7f03e5f2f3de5b494930f39791cb13bb21..ffefa8ed2dd13e6c4097d7dc2e1cd359f53b27bf 100644 (file)
--- a/Lib/test/test_typing.py
+++ b/Lib/test/test_typing.py
@@ -1471,8 +1471,8 @@ class ForwardRefTests(BaseTestCase):
     def test_meta_no_type_check(self):
 
         @no_type_check_decorator
-        def magic_decorator(deco):
-            return deco
+        def magic_decorator(func):
+            return func
 
         self.assertEqual(magic_decorator.__name__, 'magic_decorator')