Строки документации Python (или строки документации) предоставляют удобный способ связывания документации с модулями, функциями, классами и методами Python.
Он указывается в исходном коде и используется, как комментарий, для документирования определенного сегмента кода. В отличие от обычных комментариев исходного кода, строка документации должна описывать, что делает функция, а не как.
Как должна выглядеть строка документации?
- Строка документа должна начинаться с заглавной буквы и заканчиваться точкой.
- Первая строка должна быть кратким описанием.
- Если в строке документации больше строк, вторая строка должна быть пустой, визуально отделяя сводку от остального описания.
- Следующие строки должны быть одним или несколькими абзацами, описывающими соглашения о вызовах объекта, его побочные эффекты и т. д.
Объявление строк документации. Строки документации объявляются с использованием «тройных двойных кавычек»» сразу после объявления класса, метода или функции. Все функции должны иметь строку документации.
Доступ к строкам документации. Доступ к строкам документации можно получить с помощью метода __doc__ объекта или с помощью функции справки.
В приведенном ниже примере показано, как объявить строку документации и получить к ней доступ.
def my_function():
«»»
Демонстрирует строки документации и ничего не делает на самом деле.
”””
return None
print («Используя __doc__:»)
print (my_function.__doc__)
print (« Использование справки:")
help(my_function)
Вывод:
Using __doc__:
Demonstrate docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:
my_function()
Demonstrate docstrings and does nothing really.
Однострочные строки документации
Как следует из названия, строки документации в одну строку помещаются в одну строку. Они используются в очевидных случаях. Закрывающие котировки находятся на той же строке, что и открывающие. Это выглядит лучше для однострочников.
Например:
def power(a, b):
"""Returns arg1 raised to power arg2."""
return a**b
print power.__doc__
Вывод:
Returns arg1 raised to power arg2.
Многострочные строки документации
Многострочные строки документации состоят из сводной строки, как и однострочная строка документации, за которой следует пустая строка, за которой следует более подробное описание. Строка сводки может находиться на той же строке, что и открывающие кавычки, или на следующей строке.
В приведенном ниже примере показана многострочная строка документации.
def my_function(arg1):
"""
Summary line.
Extended description of function.
Parameters:
arg1 (int): Description of arg1
Returns:
int: Description of return value
"""
return arg1
print my_function.__doc__
Вывод:
Summary line.
Extended description of function.
Parameters:
arg1 (int): Description of arg1
Returns:
int: Description of return value
Отступы в строках документации
Вся строка документации имеет такой же отступ, как и кавычки в ее первой строке. Инструменты обработки строки документации лишают вторую и последующие строки строки документации одинаковое количество отступов, равное минимальному отступу всех непустых строк после первой строки. Любой отступ в первой строке строки документации (т. е. до первой новой строки) не имеет значения и удаляется. Относительный отступ более поздних строк в строке документации сохраняется.
Строки документации в классах
Давайте возьмем пример, чтобы показать, как писать строки документации для класса и его методов. help используется для доступа к строке документации.
class ComplexNumber:
"""
This is a class for mathematical operations on complex numbers.
Attributes:
real (int): The real part of complex number.
imag (int): The imaginary part of complex number.
"""
def __init__(self, real, imag):
"""
The constructor for ComplexNumber class.
Parameters:
real (int): The real part of complex number.
imag (int): The imaginary part of complex number.
"""
def add(self, num):
"""
The function to add two Complex Numbers.
Parameters:
num (ComplexNumber): The complex number to be added.
Returns:
ComplexNumber: A complex number which contains the sum.
"""
re = self.real + num.real
im = self.imag + num.imag
return ComplexNumber(re, im)
help(ComplexNumber) # to access Class docstring
help(ComplexNumber.add) # to access method's docstring
Вывод:
Help on class ComplexNumber in module __main__:
class ComplexNumber
| This is a class for mathematical operations on complex numbers.
|
| Attributes:
| real (int): The real part of complex number.
| imag (int): The imaginary part of complex number.
|
| Methods defined here:
|
| __init__(self, real, imag)
| The constructor for ComplexNumber class.
|
| Parameters:
| real (int): The real part of complex number.
| imag (int): The imaginary part of complex number.
|
| add(self, num)
| The function to add two Complex Numbers.
|
| Parameters:
| num (ComplexNumber): The complex number to be added.
|
| Returns:
| ComplexNumber: A complex number which contains the sum.
Help on method add in module __main__:
add(self, num) unbound __main__.ComplexNumber method
The function to add two Complex Numbers.
Parameters:
num (ComplexNumber): The complex number to be added.
Returns:
ComplexNumber: A complex number which contains the sum.
Пожалуйста, пишите комментарии, если вы обнаружите что-то неправильное, или вы хотите поделиться дополнительной информацией по теме, обсуждаемой выше.
