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

• 01.07.2023
• 1500
• Основы Python
• Форматирование

Docstring, или строка документации — это инструмент в Python, который используется для документирования определенных сегментов кода. Обычно docstring помещается сразу после определения функции, метода, класса или модуля.

Docstring оформляется в виде строкового литерала и может быть как однострочным, так и многострочным.

Создание Docstring

В Python docstring создается путем вставки строки (которая может быть заключена в одинарные или тройные кавычки) в верхней части функции, метода, класса или модуля.

def add_numbers(x, y):
    """Adds two numbers together."""
    return x + y

Этот docstring описывает, что делает функция add_numbers().

Docstring также может быть многострочным, что особенно полезно для более сложных функций или методов:

def complex_function(x, y, z):
    """
    This is a complex function that takes three parameters and
    does many things.
    """
    # function body

Использование Docstring

Docstring можно просмотреть с помощью функции help(), которая возвращает информацию о том, как использовать функцию, класс, метод или модуль.

help(add_numbers)

Исполнив эту команду, вы увидите вывод справочной информации, включая docstring:

Help on function add_numbers in module __main__:

add_numbers(x, y)
    Adds two numbers together.

Docstring также можно получить с помощью атрибута __doc__.

print(add_numbers.__doc__)

Стандарты оформления Docstring

Есть несколько широко распространенных стандартов оформления docstring, таких как Google, NumPy и reStructuredText (reST). Каждый из них имеет свои собственные соглашения о том, как структурировать и форматировать docstring.

Например, в стиле Google выглядит так:

def sample_function(arg1, arg2):
    """
    Summary line.

    Extended description of function.

    Args:
    arg1 (int): Description of arg1
    arg2 (str): Description of arg2

    Returns:
    bool: Description of return value
    """
    return True

Расширенное использование Docstring

Помимо базового использования в функциях и методах, Docstring также применим к классам и модулям.

Docstring классов

Когда Docstring применяется к классу, он должен содержать краткое описание того, что делает класс, а также его атрибуты и методы.

class MyClass:
    """
    This is an example class.

    Attributes:
    attr1: A string representing the attribute.

    Methods:
    method1: Prints the attribute.
    """

    attr1 = "This is an attribute"

    def method1(self):
        """Prints the attribute."""
        print(self.attr1)

Docstring модулей

В случае модулей Docstring должен быть размещен в самом начале файла. Он должен содержать описание того, что делает модуль, и его ключевые функции и классы.

"""
This is an example module.

This module demonstrates the usage of docstrings in Python.
"""

# Module code

Автогенерация документации

Один из наиболее важных аспектов использования Docstring — возможность автоматической генерации документации. Инструменты, такие как Sphinx, могут считывать ваш Docstring и автоматически создавать документацию в форматах HTML, PDF и других.

Заключение

Docstring является важным инструментом в Python, который используется для документирования вашего кода. Он описывает, что делает ваша функция, метод, класс или модуль, что помогает другим разработчикам понять ваш код. Важно следовать определенным стандартам оформления docstring, чтобы обеспечить последовательность и четкость вашей документации.