Python - PyDoc - докуменирование
Primary tabs
Всем доброго времени суток. Хочу немного заострить внимание на документировании кода в 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
docoDESCRIPTION
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 symbolDATA
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
Как видно, документация ведётся просто и понятно. Так что, для удобство НЕ ЛЕНИТЕСЬ проделать столь простые операции и добавлять строки документирования к вашим модулям. О том как их лучше оформлять - посмотрите и поэкспериментируйте со встроенными функциями стандартных модулей)))
Прекрасного вам настроения)))
- Log in to post comments
- 8263 reads