Так как сейчас в свободное от основной работы время занимаюсь разработкой пары небольших программ для использования в Linux и, возможно, в будущем в Windows, то решил, что было бы не плохо сохранить кое-какую важную информацию по исходному коду. Для того, чтобы не забивать исходники большим количеством комментариев, то подумал, что было бы не плохо сгенерировать всю информацию автоматически, сохранить в HTML, а когда будет готов проект – можно будет спокойно удалить лишние комментарии с подробным описанием и в любой момент обращаться к уже сгенерированной документации.
В принципе, в состав Lazarus уже входит утилита FPDoc, которая может сохранять необходимую информацию в xml-файлы, есть так же и LazDoc – отдельный проект для работы с документацией в Lazarus, но мне, честно говоря, жутко лень разбираться в их работе, поэтому решил воспользоваться под Lazarus’ом тем, что уже однажды использовал – утилитой PasDoc.
Вообще, для таких целей как автодокументация исходного кода, мне больше по душе Doc-O-Matic 6 Express — тоже бесплатная программа (именно Express-версия), о которой я упоминал в посте «Инструментарий Delphi-программиста. Кто с чем, зачем и почему?«. Однако, к сожалению, Doc-O-Matic под Linux я не встречал, а PasDoc – имеет открытый исходный код, написанный на том же Free Pascal – следовательно могу сам под себя под любой ОС собрать утилиту и использовать её по назначению.
Итак, что имеется на старте: Lazarus 0.9.29 с FPC 2.5.1, исходный код программы в кодировке UTF-8.
Требуется: создать документацию для исходного кода программы в HTML-формате.
В тонкости работы с разметкой комментариев я углубляться не буду, так как есть замечательная статья на русском языке (хоть и немного устаревшая), в которой подробно описаны все параметры командной строки PasDoc.
Однако, если скачать последний бинарник PasDoc и попробовать сгенерировать документацию на русском языке – нас может постигнуть небольшое разочарование, а именно – отсутствие поддержки utf-8. Все русские буквы, соответственно, превращаются в кракозябры. Но я не зря упомянул в начале, что PasDoc имеет открытый исходный код Free Pascal.
И первое наше действие – выгружаем исходники PasDoc из SVN-репозитория себе на компьютер. Адрес репозитория:
svn co https://pasdoc.svn.sourceforge.net/svnroot/pasdoc/trunk
Загрузка пройдет довольно быстро. Теперь в директории с исходниками у нас есть директория source, которая и содержит всё для нас необходимое. Вначале заходим в \source\console\ там находятся исходники для компиляции консольной версии PasDoc. Собрать можно как под Lazarus’ом, так и под Delphi до версии XE включительно. Собираем консольную версию PasDoc и переносим её в любое удобное для Вас место. К ней мы ещё вернемся, а пока рассмотрим, что ещё есть в исходниках. Дополнительно мы можем установить набор компонентов PasDoc опять же как для Lazarus, так и для Delphi. Я ставил под компоненты Lazarus — в принципе, достаточно удобные компоненты для создания собственных GUI-приложений на основе PasDoc. Если лень собирать с нуля свое приложение, то можно воспользоваться уже готовыми проектами для Delphi и Lazarus, которые находятся в директориях gui_delphi и gui соответственно.
Теперь, что касается генерации исходного кода. Та версия PasDoc, которую мы только что собрали из SVN – прекрасно понимает utf-8. Остается только её приспособить под работу с исходниками. Пробовал добавить PasDoc в Lazarus как внешнее средство, но, к сожалению, не получилось указать в параметрах сразу все файлы проекта – максимум удалось создать документацию по последнему открытому модулю.
Поэтому решил сделать небольшой “ход конем”. Чтобы не прописывать каждый раз все параметры командной строки для PasDoc, работая в Windows можно поместить в директорию с проектом небольшой bat-ник, содержащий всего одну строку:
ПУТЬ_ДО_ПРОГРАММЫ/pasdoc.exe --output=documentation –language ru.utf8 --write-uses-list *.pas
Теперь создаем в директории с проектом ещё одну с названием documentation и, можно сказать, все готово. Запускаем bat-ник и PasDoc создает в указанной директории справку по всем pas-файлам из директории проекта.
Для подобной же операции, но под Linux так же есть готовое решение. Достаточно создать опять же в директории с проектом следующий bash-скрипт:
PasDoc \ --output=documetation/ \ --write-uses-list \ –-language ru.utf8 \ `find source/ -iname '*.pas' ` \ $@
Этот скрипт не мой — я его только немного укоротил под свои нужды. Полный вариант скрипта можно посмотреть на официальном сайте PasDoc. Вот теперь можно спокойно заниматься разработкой программы :) И не важно в какой ОС вы это делаете. Документация прекрасно собирается в кодировке UTF-8. Если необходима другая кодировка — просто меняем значение параметра —language и продолжаем работать дальше.