В Python есть возможность читать встроенную в код документацию с помощью двух инструментов, а также писать собственную.
Рассмотрим, как это можно делать:
Получаем документацию с помощью метода help()
Вызов метода help(), возвращает полную справку о переданной функции/объекте.
Синтаксис:
print(help(<объект справки>)
Например:
Справка вернула полную информацию о List-e, включая методы его исходного кода(их намного больше, так как все перечислять слишком долго).
Это работает со всеми стандартными функциями и объектами.
Мы получили слишком много ненужной информации, которую не будем использовать. Как же получить только самое главное?
Получаем документацию с помощью атрибута __doc__
Сделаем тоже самое, но только используя атрибут __doc__
Синтаксис:
print(list.__doc__)
Если мы хотим узнать, например как работает стандартный метод строки - split(), то синтаксис будет выглядеть так:
print(str.split.__doc__)
Атрибут вернул только так называемый docstring, если посмотреть выше, то эти же строки содержит вывод help() в начале.
docstring - это такая строковая переменная, которая позволяет получить доступ к встроенной в код документации.
То есть, встроенный класс list, в исходниках выглядит примерно так, точнее его начало:
Синтаксис docstring-a - тройные кавычки.
Вызывать вывод docstring намного проще чем help(), так как он обычно содержит исчерпывающую информацию о функции, синтаксисе и возможных особенностях того, что нас интересует.
Это работает со всеми стандартными функциями и объектами.
Пишем собственную документацию
Соответственно, если мы знаем синтаксис переменной документации, то можем сами её писать к своему коду? Конечно, да.
Напишем функцию сложения чисел:
И добавим к ней документацию:
Теперь сравним два метода получения документации рассмотренных выше, уже на нашей собственной функции:
И их выводы:
help()
Здесь нам вывело шаблон в виде названия функции, её документации, и то что она находится в модуле __main__.
__doc__
Атрибут вывел только сам docstring, что является намного удобнее так как не захламлено лишним.
Кстати, требование к документации модулей, классов и функций заложена в рекомендации к стилистике кода PEP8.
Потому что наличие документации облегчает чтение чужого кода, тем более когда мы имеем такие удобные инструменты быстрого получения интересующей нас информации, если конечно документация грамотно написана
