Что такое docstring? С чем его едят?

Docstring - это такая строковая переменная, которая идет сразу за объявлением модуля, функции, класса, метода. Таким образом питон предоставляет удобный способ добавления документации. Существует много средств для автоматического генерирования документации, которые используют докстринг. Докстринг очень похож на комментарий, но заключается в тройные кавычки. Все функции должны иметь докстринг, который содержит описание работы этой функции. Комментарии же обычно пытаются объяснить эту работу. На первой строке пишем короткую фразу, такую как: “Решает уравнение ax^2+ bx + c =0”. Ниже идет более подробный разбор различный случаев. Достать соответствующий докстринг можно, обратившись к атрибуту doc объекта.

Примеры использования

Теперь давайте посмотрим на докстринг в действии.

"""Это докстринг модуля, он однострочный."""


def function(a,b,c):
    """Эта функция содержит многострочный докстринг.

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

class  UselessClass(object):
    """Это класс с докстрингом."""

    def method_of_class(self):
        """А это метод с докстрингом"""

Для того чтобы увидеть результат работы мы можем выполнить несколько команд:

import test_docstring

print(test_docstring.__doc__)
print(test_docstring.function.__doc__)
print(test_docstring.UselessClass.method_of_class.__doc__)
help(test_docstring.UselessClass)

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

Для чего ещё может быть использован докстринг, описано в документе PEP 257.