Docstring Python: как правильно оформлять, примеры использования

Docstring в Python – это строковый литерал (строку, заключенную в тройные кавычки), который предназначен для описания функций, классов, модулей и методов. Он располагается в начале классов и функций, и содержит информацию о том, как использовать данную функцию или класс, а также примеры кода и описание параметров.

Вот пример docstring для функции:

python
def my_function(param1, param2):
    """
    Описание функции
    :param param1: описание первого параметра
    :param param2: описание второго параметра
    :return: описание возвращаемого значения
    """
    return param1 + param2

Docstring начинается с тройных кавычек, а заканчивается тремя такими же кавычками. На первой строке можно добавить краткое описание функции. Затем в docstring можно добавить параметры функции (с помощью :param) и описание возвращаемого значения (с помощью :return).

Помимо этого, docstring может содержать дополнительные параметры, такие как :raises, :type и др.

Который извлекает docstring из функции и выводит его на экран. Это можно сделать с помощью атрибута __doc__, например так:

python
def my_function(param1, param2):
    """
    Описание функции
    :param param1: описание первого параметра
    :param param2: описание второго параметра
    :return: описание возвращаемого значения
    """
    return param1 + param2
print(my_function.__doc__)

Вывод на экран:

Описание функции
    :param param1: описание первого параметра
    :param param2: описание второго параметра
    :return: описание возвращаемого значения

Кроме того, docstring может быть использован в качестве документации, автоматически генерируемой с помощью различных инструментов, таких как Sphinx.