Строки документации в Python. Документирование модуля, класса, методов

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

Основное назначение комментариев – пояснить что делает код, как он работает. Основное назначение строк документации – кратко описать в целом для чего предназначен объект, какие аргументы принимает, и что возвращает.

В исходном коде Python строки документации заключаются в тройные кавычки и пишутся сразу под заголовком объекта. Пример документированного модуля:

"""Модуль содержит классы плоских фигур."""
 
from math import pi, pow
 
 
class Rectangle:
    """Класс Прямоугольник."""
 
    def __init__(self, a, b):
        """Конструктор принимает длину и ширину."""
        self.w = a
        self.h = b
 
    def square(self):
        """Метод для вычисления площади."""
        return round(self.w * self.h, 2)
 
    def perimeter(self):
        """Метод для вычисления периметра"""
        return 2 * (self.w + self.h)
 
 
class Circle:
    """Класс Круг."""
 
    def __init__(self, radius):
        """Конструктор принимает радиус."""
        self.r = radius
 
    def square(self):
        """Метод для вычисления
        площади круга."""
        return round(pi * pow(self.r, 2), 2)
 
    def length(self):
        """Метод для вычисления
        длины окружности."""
        return round(2 * pi * self.r)

Извлекать строки документации можно двумя способами:

• Через встроенный для каждого объекта атрибут-переменную __doc__.

• С помощью встроенной в Python функции help, которая запускает интерактивную справочную систему.

>>> import planimetry
>>> planimetry.Rectangle.__doc__
'Класс Прямоугольник.'
>>> print(planimetry.__doc__)
Модуль содержит классы плоских фигур.

Если дать команду help(planimetry), то будут выведены все строки документации модуля в структурированном виде. Однако можно "заказывать" справку по отдельным объектам:

>>> help(planimetry.Circle.length)
Help on function length in 
module geometry.planimetry:

length(self)
    Метод для вычисления
    длины окружности.

Выход из справки осуществляется с помощью клавиши q.

В Python документированы все встроенные объекты и модули библиотеки.

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

>>> import math
>>> print(math.trunc.__doc__)
Truncates the Real x to the nearest Integral toward 0.

Uses the __trunc__ magic method.
>>> 

Таким образом, если вам надо узнать, для чего предназначена та или иная функция, и как она работает, это всегда можно сделать, не выходя из интерпретатора Python. Перечень атрибутов модуля или объекта можно посмотреть с помощью встроенной функции dir().

Следует отметить, документирование модулей принято выполнять на английском языке. Многие проекты имеют открытый код, выкладываются в Веб, их смотрят и дорабатывают программисты из разных стран. Использование одного языка позволяет им понимать друг друга. Поэтому профессиональный программист должен владеть английским хотя бы на начальном уровне. Google Translate – тоже вариант.

Практическая работа

Выполните полное документирование модуля, созданного в практической работе прошлого урока.

Курс с примерами решений практических работ:
pdf-версия