Есть ли способ отделить строки документации от функций, которые они документируют?

Question

Я работаю над модулем со множеством небольших функций, но строки документации имеют тенденцию быть довольно длинными.Строки документации делают работу с модулем раздражающей, поскольку мне приходится постоянно пролистывать длинную строку документации, чтобы найти немного реального кода.

Есть ли способ отделить строки документации от функций, которые они документируют?Мне бы очень хотелось иметь возможность указывать строки документации в конце файла отдельно от кода или, что еще лучше, в отдельном файле.

Answer 1

Строка документации для функции доступна в виде специального атрибута __doc__.

>>> def f(x):
...     "return the square of x"
...     return x * x
>>> f.__doc__
'return the square of x'
>>> help(f)
(help page with appropriate docstring)
>>> f.__doc__ = "Return the argument squared"
>>> help(f)
(help page with new docstring)

Это все равно демонстрирует технику.На практике вы можете:

def f(x):
    return x * x

f.__doc__ = """
Return the square of the function argument.

Arguments: x - number to square

Return value: x squared

Exceptions: none

Global variables used: none

Side effects: none

Limitations: none
"""

... или все, что вы хотите добавить в свои строки документов.