CKTIS / Python
docstring — документационен низ
Docstring е обикновен низов литерал (нито f-низ, нито t-низ), използван като първи оператор в модул, клас или функция. Той описва предназначението на обекта и е достъпен чрез __doc__; не е коментар, започващ с #.
Версия: Python 3.14; repository image, production runtime not attested
Синтаксис
def function_name():
"""Describe the function's purpose."""
passdocstring е обикновен низов литерал (нито f-низ, нито t-низ), поставен като първи оператор в модул, клас или функция, включително метод. Python го предоставя като атрибут __doc__ на обекта. Инструментите могат да използват това съдържание, за да показват документация.
Нито форматираният низов литерал (f-низ), нито шаблонният низов литерал (t-низ) създава docstring, дори ако литералът не съдържа полета за заместване и е първият оператор. Ако първият оператор във функцията е f"""Description.""", нейният атрибут __doc__ има стойност None.
Коментар, започващ с #, не създава docstring. Самостоятелен низов литерал, поставен след друг оператор, също не става основният docstring на обекта. Тройните кавички """...""" са удобни, особено за няколко реда, но сами по себе си не са достатъчни: от значение са както видът на литерала, така и мястото му.
Според конвенцията първият ред трябва накратко да описва предназначението на обекта, да започва с главна буква и да завършва с точка. Отделете допълнителното описание с празен ред; при нужда обяснете аргументите, резултатите и страничните ефекти. Това са препоръки за съдържанието, а не синтактични изисквания.
В примера square.__doc__ предоставя описанието, а square(5) изчислява резултата независимо от документацията. Опцията -OO премахва docstring-овете, затова кодът на приложението не бива да разчита на наличието им.
Примери
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Резултат
Return the square of number. 25
Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.