Python - PyDoc - докуменирование

Всем доброго времени суток. Хочу немного заострить внимание на документировании кода в Python. Хотя сам этот язык своим синтаксисом заставляет людей писать удобночитаемый и красивый код (отучивает от быдлокодерства), но всё же документация не помешает, и тут Python на высоте.
Для тех, кто будет разбираться в вашем коде нужно делать, как и везде, короткие пометки в виде обычных комментариев, начинающихся с символа #. Но это довольно известная мера, и о ней стоило только напомнить.
А вот что делать, если вы создали модуль для использования другими людьми, да и при разработке в команде (как и в нашем случае), как подать удобную документацию "без напряга" ?
Выход есть - это встроенная справка, и средства Питончика))) Итак, первое что мы можем сделать как пользователи модуля - вызвать функцию dir() передав аргументом что угодно, переменную, тип, модуль и эта функция выдаст список содержимого. Но список содержимого - это маловастенько)))
Но есть ещё и строки документации - это строки, следующие прямо за описываемым модулем (функцией, классом), они должны располагаться в самом начале модуля (функции, класса). Перед ними могут быть только комментарии. С помощью атрибута __doc__ можно получить доступ к этой справке.
Но вышеуказанный способ не самый удобный. С помощью встроенного в язык инструмента PyDoc можно творить "чудеса", но описание "чудес" выходит за рамки статьи. Скажу лишь об функции help() которая анализирует объект, и на основе анализа, и в том числе строк документации выводит справку.

Ну хватит болтовни - Айда примерам!
Итак, я создаю простенький файл doco.py, который потом буду импортировать как модуль в интерактивной оболочке. Строки документирования - это обычная строка (строки), которая стоит в начале чего-то (модуля, функции, класса) и ничему не присваивается, я использую три кавычки для обеспечения многострочного ввода.

"""
This file hase doc))))
Bad boys, bad boys! What you gonna do? What you gonna do, when we come for you?
"""
# выше располагается строка документирования к файлу
for i in range(3): print ("hi")
x = [1,2,3,4,5,6]

def rr(x):
#заметьте, что коментарии могут идти до строк документирования
#строки документирования должны такде иметь отступы как и внутренние инструкции
	"""
	doc about function
	i can tell you my secret
	it print poping symbol
	"""
	print(x.pop())

rr(x)
rr(x)
print("end")

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

Python 3.2.1 (default, Jul 18 2011, 16:24:40) [GCC] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import doco  #импортируем наш модуль
hi
hi
hi
6
5
end
>>> dir(doco)        #смотрим содержимое модуля
['__builtins__', '__cached__', '__doc__', '__file__', '__name__', '__package__', 'i', 'rr', 'x']
>>> help(doco)     #вызываем помощь по нашему модулю, смотри ниже.

>>> help(doco.rr)  # вызываем справку по нашему методу, смотри ниже.

>>> y = [1,2,'t',5]  #создаём тестовый список
>>> doco.rr(y)
5
>>> doco.rr(y)     
t
>>> doco.rr(y)       #вызываем метод нашего модуля
2
>>> y                     #как видим список изменился, pop работает
[1]

При вызове help(doco) был следующий вывод:

Help on module doco:

NAME
doco

DESCRIPTION
This file hase doc))))
Bad boys, bad boys! What you gonna do? What you gonna do, when we come for you?

FUNCTIONS
rr(x)
doc about function
i can tell you my secret
it print poping symbol

DATA
i = 2
x = [1, 2, 3, 4]

FILE
/home/p***l/doco.py

При вызове help(doco.rr) вывод:

Help on function rr in module doco:

rr(x)
doc about function
i can tell you my secret
it print poping symbol

Как видно, документация ведётся просто и понятно. Так что, для удобство НЕ ЛЕНИТЕСЬ проделать столь простые операции и добавлять строки документирования к вашим модулям. О том как их лучше оформлять - посмотрите и поэкспериментируйте со встроенными функциями стандартных модулей)))

Прекрасного вам настроения)))