Не секрет, что каждый из тех, кто разрабатывает программы для микроконтроллеров, частенько использует чужие исходные тексты - либо как источник идей для собственных программ, либо непосредственно, как «библиотечку» функций. И так же не является тайной, что большинство добываемых в сети исходников не так-то просто понять. Иной раз программа представляет собой даже не форматированный (то есть без отступов) текст без комментариев!

Разумеется, пользоваться такими «библиотеками» довольно неудобно. Спрашивается: если уж решил поделиться исходником с общественностью, почему так неаккуратно оформил его? Или почему не сопроводил подробным описанием?

Я понимаю - лень-матушка... Ведь качественное документирование программ требует порой усилий не меньших, чем собственно написание программы. Но есть средства, существенно облегчающие эту задачу, с одним из которых я хочу вас познакомить. Это средство «самодокументирования» под названием Doxygen.

Прежде всего, Doxygen - это бесплатный проект, распространяемый по лицензии GNU, то есть вы можете его скачать с официального сайта и совершенно законно использовать для любых проектов, в том числе коммерческих. На западе этот продукт используется программистами весьма широко, особенно сообществом GNU-программистов. Кстати, почти вся документация для GCC (многим больше известна версия под названием WinAVR) сделана именно при помощи этого средства - прямо из комментариев в тексте программ!

Итак, что, собственно говоря, Doxygen делает? Он сканирует исходные тексты программ, выискивает в них комментарии, оформленные особым образом, и строит на основе этих комментариев и исходного текста файлы документации. Т.е. вы получаете сразу готовые к просмотру HTML или RTF-файлы, содержащие достаточно подробную, грамотно структурированную информацию о константах, макросах, переменных, функциях ваших исходников. Если формат документа поддерживает возможность гиперссылок - они будут интегрированы для удобства навигации по тексту.

Наибольшее достоинство применения этой технологии в том, что практически не делается «лишняя» работа: комментарии в тексте программы сразу же являются и текстом документации. Правда, для получения наилучшей документации придется писать комментарии чуть более тщательнее.

Возможностей Doxygen очень много, но осваивать сразу все вовсе не обязательно! Минимум, с чего нужно начать - это знакомство с форматом комментариев, воспринимаемых этой системой. В некоторых случаях этого будет уже достаточно для получения приличной документации к программе. Оговорюсь, что Doxygen поддерживает большое число языков программирования, но я буду рассказывать только о Си. Но программисты, работающие с Java, PHP, Pascal и другими языками могут использовать Doxygen с не меньшим успехом (в качестве примера приведу справочную систему к пакету JEDI Code Library для Delphi, которая так же получена при помощи [Doxygen). Еще одна оговорка: Doxygen обычно имеет несколько способов решения одной и той же проблемы, но я буду рассказывать только об одном из вариантов, который с моей субъективной точки зрения наиболее подходящий, а все желающие могут изучить документацию (на английском).

Виды комментариев.

Doxygen обрабатывает однострочные комментарии, обозначенные тремя символами «косой черты», т.е. ///. Идущие подряд однострочные комментарии объединяются в один общий блок-параграф. Однострочные комментарии, разделенные строками операторов программы, попадают в разные параграфы.

/// Этот комментарий обработается Doxygen
/// Эта строка будет «прилеплена» к предыдущей (и отделена пробелом)
// эта строка будет проигнорирована Doxygen

Так же Doxygen обрабатывает многострочные комментарии типа /* */, но необходимо, чтобы число звездочек в начале комментария было не менее двух, т.е. обрамление комментария должно быть таким:

/** этот комментарий
обработается Doxygen
*/
/* этот комментарий
будет проигнорирован Doxygen
*/

Варианты документирования при помощи комментариев.

Doxygen анализирует структуру текста программы, выделяя отдельные модули (файлы), глобальные определения (переменные, макросы и т.п.), находит функции и локальные для функций элементы. Комментарии, находящиеся «внутри» функционального блока программы, группируются. То есть комментарии внутри функции будут относиться к документации на эту функцию, а комментарии, разбросанные «между» функциями, будут собраны в документацию на весь файл.

Для документирования всего файла целиком лучше всего использовать многострочный комментарий, расположенный в самом начале файла. Такую «шапку» делают почти всегда, остается лишь оформить ее достойно. Для достойного оформления можно использовать внутри многострочного комментария специальные параметры Doxygen. Параметром называется определенное ключевое слово (далее - просто ключ), которое служит для уведомления Doxygen выполнить особую обработку следующего (или следующих) слов комментария. Чтобы отделить ключевое слово от текста комментария, каждое ключевое слово начинается с ESC-символа «обратная косая черта» (аналогично «\n»). Вот несколько наиболее ходовых ключей:

\file - все символы в строке после этого ключа будут выделены особо и будут использованы для «заголовка» описания всего файла. Все прочие строки многострочного комментария будут считаться описанием файла. Если таких ключевых слов будут обнаружено несколько, то все строки после ключей будут собраны в один блок, размещаемый в начале описания файла.

\mainpage - все символы в строке после этого ключа будут использованы для оформления заголовка всей документации к проекту, а все строки после - в качестве описания всего проекта. Помещаемого на первой (титульной) странице документации. Если эти ключи будут найдены в разных файлах, то все описатели будут собраны в общий «титульный» блок.

Следующие ключи служат для аналогичных целей:

\autor - обозначает автора проекта
\note - примечание
\par - начинает новый параграф
\n - начинает новую строку
\date - обозначает дату
\version - обозначает версию проекта (файла)
\brief - обозначает начало краткого описания. Отменяет действие блока \file.

Для описания отдельной переменной или макроса следует непосредственно перед строкой с определением добавить однострочный комментарий в стиле Doxygen, например так:

/// Переменная-счетчик повторений расчетов
int Counter = 12;
/// Максимальное число итераций
#define MAX_IT 123

Учтите, что Doxygen по умолчанию не документирует static-переменные.

Описание функции (класса и т.п.) более сложное. Желательно делать его при по-мощи многострочного комментария по следующему шаблону:

/** заголовок (краткое описание)
* подробное описание (несколько строк,
* начинающихся со звездочки)
* список входных параметров (см. далее)
* @return описание возвращаемого значения
*/

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

Список параметров - нужное количество строк, начинающихся с символа «*» и содержащие ключевое слово @param, за которым через пробел следует параметр функции с описанием. Вот пример правильно оформленного описания функции:

/** Вычисление куба числа
* Вычисляет целое значение куба числа
* @param d - число для возведения в куб
* @return - возвращает куб числа
*/
long cube(int d){
}

Разумеется, любая часть комментария может отсутствовать.

Использование «интеллектуальных» особенностей Doxygen.

Одна из очень полезных возможностей Doxygen - это способность строить перекрестные ссылки. Например, если в комментарии вы просто упомяните уже прокомментированную функцию, Doxygen оформит это упоминание, как гиперссылку на нужный элемент.

Если необходимо оформить гиперссылку на макрос или переменную, следует предварять его упоминание символом «#», ибо Doxygen автоматически делает гиперссылки только на функции и методы классов.

Любое слово можно выделить жирным шрифтом, если перед ним указать ключ \b. Если нужно выделить группу слов жирным шрифтом, следует воспользоваться парными html-тегами <b></b>. При помощи парных тегов <i></i> и <u></u>  можно выделить группу слов наклонным или подчеркнутым шрифтом соответственно. Парные теги могут быть вложены друг в друга.

Собственно говоря, уже этих сведений достаточно, чтобы получить вполне приличную документацию к программе. Неупомянутыми остались примерно 90% функций и возможностей Doxygen - можете представить себе, что он умеет!
Однако, как же теперь получить документацию из прокомментированного текста программы? Напомню, что Doxygen - это программа по лицензии GNU, а история возникновения самого термина приводит нас к unix-программистам (теперь уже *nix), для которых командная строка - мать родная! Но увы, лично мне командная строка не нравится, и необходимость работы с ней я воспринимаю, как неизбежное зло, которого следует избегать всеми силами. Благо, что в случае Doxygen для этого особых усилий прилагать не придется - в состав пакета входит «мастер», при помощи которого все можно сделать практически привычным для всех способом.

Прежде чем рассмотреть этот самый «мастер», снова оговорюсь, что я не намерен рассматривать все его возможности, а остановлюсь только на тех, которые мне кажутся наиболее важными для повседневных целей обычных людей, и которыми вполне можно ограничиться.

На рисунке показан скриншот основного окна мастера.

Работа с мастером заключается в трех шагах: Step1 - конфигурирование, Step 2 - сохранение настроек и Step 3 - запуск Doxygen.

Конфигурирование может производиться при помощи еще одного мастера - кнопка Wizard, что подходит для большинства обычных пользователей. Если требуется более тонкая настройка работы - следует нажать кнопку Expert для работы с массой индивидуально настраиваемых параметров. Эта возможность будет рассмотрена вскользь далее. Наконец, если документирование осуществляется уже не первый раз - можно использовать ранее сохраненные настройки, для чего следует нажать кнопку Load и указать кон-фигурационный файл, обычно имеющий имя «Doxyfile» (без расширения).

Рассмотрим мастер конфигурации подробнее.

Его окно содержит 4 закладки - Project, Mode, Output и Diagrams.

На закладке Project настраиваются главные параметры документирования проекта. Можно задать имя проекта (поле Project Name) и его версию (поле Project version id). обязательно следует указать папку, в которой содержатся исходные файлы проекта (поле Source code directory). Если отметить опцию Scan recursively, то будут просканированы все вложенные папки и найденные там исходные тексты программ будут обработаны. Так же необходимо указать папку, в которой Doxygen будет формировать результирующие файлы документации (поле Destination directory).

Можно указать, следует ли включать в документацию элементы программы. которые не прокомментированы должным образом, выбрав опцию All entries. В противном случае в документацию включаются только корректно прокомментированные элементы. Дополнительно можно отметить опцию Include cross-referenced source code in the output, и в документацию будет включен красиво оформленный исходный текст программ с гиперссылками.
Так же нужно указать язык программы, выбрав из 4-х предлагаемых вариантов.

На закладке Output настраивается формат выходной документации.

Doxygen может создать документацию в нескольких распространенных форматах: HTML, LaTeX , Man , RTF и XML. Генерация в соответствующем формате осуществляется, если выбрана соответствующая опция. Так как применение LaTeX представляется мне весьма проблематичным¹, рассмотрим параметры генерации только в формате HTML.

Имеется три способа формирования HTML-документации: в виде обычного HTML (plain HTML), в виде документа с фреймами и деревом навигации (with frames and a navigation tree) и в виде скомпилированного CHM-файла. Для распространения наиболее удобным представляется именно третий вариант, однако он подразумевает наличие у вас компилятора CHM-файлов. Вариант с фреймами и деревом навигации имеет некоторые проблемы с кодировкой, т.е. проблемы с отображением русских символов в дереве навигации (возможно, это глюк Internet Explorer).

Теоретически можно включить опцию With search function, чтобы внедрить в документацию механизм поиска по ключевым словам, но это опять-таки малоприемлемо, т.к. требует наличия WEB-сервера с поддержкой PHP. В общем, выбор вариантов не велик.

Формат RTF удобен тем, что может быть открыт в любом текстовом процессоре и откорректирован вручную.

Закладка Diagrams позволяет настроить режим внедрения в документацию диаграмм, показывающих иерархию классов и т.п. связи между составными частями проекта. Так как речь идет о документировании программ на Си, а не С++, эти возможности не рассматриваются - рекомендую выбирать опцию No diagaram (без диаграмм).

Итак, при помощи мастера сделаны необходимые конфигурации. Но прежде, чем продолжать, сделаю важное примечание: по умолчанию Doxygen создает документы в кодировке UTF-8, а исходные тексты, как правило, мы создаем в кодировке Windows-1251, в результате скорее всего будет получен HTML-документ с кракозямбами вместо русского текста. Исправить эту ситуацию и, заодно, более тонко настроить параметры Doxygen можно, воспользовавшись экспертным режимом, т.е. нажав на кнопку Expert.

Как видите, закладок в мастере экспертных настроек существенно больше, не говоря уже о том, что в каждой закладке параметров столько, что приходится прокручивать содержимое. К счастью, окно мастера может быть распахнуто на весь экран. Еще раз повторюсь: я расскажу лишь о некоторых опциях этого режима!

На закладке Project мы сразу же видим поле указания кодировки выходного файла. По умолчанию там указано UTF-8, а необходимо ввести вручную Windows-1251. Чуть ниже следует указать язык - в списке OUTPUT_LANGUAGE выбрать Russian. Остальные опции на этой закладке можно оставить по умолчанию.

Теперь следует перейти на закладку Input.

В первую очередь на этой закладке нас интересует поле INPUT_ENCODING - снова вручную вводим Windows-1251. Теперь уже с русским языком проблем не будет.

В принципе, назначение всех полей на этой закладке вполне понятно: задаются маски и/или пути поиска файлов, обрабатываемых или наоборот, исключаемых из обработки Doxygen. Если вдруг требуется исключить какие-то файлы, надо указать их в поле EXCLUDE, пополнив его при помощи кнопок Select.

Из остальных закладок я выделю еще одну: закладку RTF.

Здесь желательно отметить опции COMPACT_RTF (для получения файла умень-шенного размера) и RTF_HYPERLINKS (для получения гиперссылок внутри RTF-документа).

На этом этап настройки может быть завершен. Далее следует сохранить сделанные настройки, а после чего - смело нажать кнопку Start. Несколько секунд ожидания, сопровождаемого сообщениями в окошке Output produced by doxygen - и можно заглянуть по ранее указанному пути в поисках результатов.

Надеюсь, вы оцените возможности автоматического самодокументирования программ, и ваши исходные тексты станут образцом для других. В качестве примера предлагаю ознакомиться с include-файлами из комплекта WinAVR - все они просто нашпигованы комментариями Doxygen. Кроме этого, взгляните на мою библиотечку для приема кодов пультов дистанционного управления бытовой техникой - мой первый опыт активного использования Doxygen «на публику».

Особенно приятно пользоваться возможностями Doxygen в IDE программиста Eclipse Ganymede, которая умеет автоматически создавать шаблоны комментариев для функций, файлов, классов, методов и т.п. Возможно, я когда-нибудь немножко расскажу и об этой IDE, ибо считаю ее очень удобной и, главное, так же абсолютно бесплатной.

¹⁾ LaTeX - это очень продвинутая система авторской разметки текста, однако, очень громоздкая (распространяется в виде многомегабайтных архивов). Кроме того, во многих случаях это коммерческая система. Все остальное расскажет Internet.

Скачать doxygen с официального сайта
Скачать образец HTML-документации
Скачать образец RTF-документации

Коментарии (1)

Только зарегистрированные пользователи могут оставлять коментарии.
Пожалуйста зарегистрируйтесь или войдите в ваш аккаунт.