1.3. Документирование функций

В языке Python вы можете документировать функции, снабжая их строками документации.

Пример 1.4. Определение строки документации для buildConnectionString


def buildConnectionString(params):
    """Создает и возвращает строку соединения из словаря параметров."""

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


	Утроенные кавычки являются удобным способом определения строк, содержащих одновременно одинарные и двойные кавычки, аналогично `qq/.../` в Perl.

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


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

Дополнительная литература

В Python Style Guide обсуждается, как написать хорошую строку документации.
Python Tutorial описывает общепринятую разбивку строк документации.

OpenSource.com.ua – Диски с Linux, FreeBSD, документация, атрибутика. CD от 5 грн, DVD от 17.95 грн!
ASPLinux 9.2 3CD - 15 грн. SUSE 9.2 DVD - 24.95 грн.	Debian Sarge 13 CD - 52 грн. Fedora Core 3 4CD - 20 грн.	Linux XP Pro 4CD - 20 грн. Mandrake 10.1 4CD - 25 грн.	FreeBSD 5.3 3CD - 15 грн. Кружка "Linux" белая - 19.95 грн.