Question

我试图记录装饰者，但我不确定文档字符串应该去哪里。从技术上讲，它是包含我想要记录的参数的内部包装器，但是用户将要将外部函数名称应用为装饰器。

例如，

east = 2deltaY
west = -2deltaY
north = 2deltaX (-2deltaX due to inverse of y axis)
south = -2deltaX (2deltaX due to inverse of y axis)
north-east = 2deltaY -2deltaX (2deltaY +2deltaX due to inverse of y axis )
north-west = -2deltaY -2deltaX (-2deltaY +2deltaX due to inverse of y axis )
south-east = 2deltaY +2deltaX (2deltaY -2deltaX due to inverse of y axis )
south-west = -2deltaY +2deltaX (-2deltaY -2deltaX due to inverse of y axis )

在上面，doc字符串是在change_case（）还是_wrapper（）之后。我倾向于前者。

Answer 1

将实际装饰器的文档放在顶级装饰器函数中。当用户尝试使用装饰器时，他们希望找到它的文档。例如，从标准库中取出functools.singledispatch装饰器：

>>> from functools import singledispatch
>>>
>>> print(singledispatch.__doc__) # the decorator has it's documentation in the actually decorator function
Single-dispatch generic function decorator.

    Transforms a function into a generic function, which can have different
    behaviours depending upon the type of its first argument. The decorated
    function acts as the default implementation, and additional
    implementations can be registered using the register() attribute of the
    generic function.


>>>

但是，您还应该使用functools.wraps将修饰函数中包含的任何文档传输到包装函数：

>>> from functools import wraps
>>>
>>> def dec(func):
...     @wraps(func)
...     def wrap(*args, **kwargs):
...         return func(*args, **kwargs)
...     return wrap
...
>>> @dec
... def func():
...     """Docstring here"""
...
>>> print(func.__doc__)
Docstring here
>>>

在哪里放置装饰器的doc字符串

1 个答案: