Главная arrow Статьи arrow Самодокументирование программ  
13.12.2017 г.
Главная
Проекты
Статьи
Начинающим
Архив новостей
Ссылки
Контакты
Поиск
Файлы
Форум
Карта сайта
Авторизация





Забыли пароль?
Ещё не зарегистрированы? Регистрация
Поддержи наш сайт!
Через WebMoney

 R785211844650
 Z210696637574
 E368177590409

Простые устройстваОтличные товары по превосходным ценамОтличные товары по превосходным ценам
Самодокументирование программ Печать E-mail
Рейтинг: / 10
ХудшаяЛучшая 
Автор ARV   
18.02.2009 г.

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

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

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

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

Image

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

 

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

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

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

Image

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

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



На закладке Mode настраивается режим обработки.

Image

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

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

Image

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

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

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

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

Image

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

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

Image

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

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

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

Image

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

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

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

Image

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

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

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

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

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

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

 


Добавить в любимые (1) | Просмотров: 25813

  Коментарии (1)
 1 Написал(а) Вадим, в 23:26 20.02.2009
Хорошая вещь, когда я в универе учился, эта прога могла быть незаменимой для меня, но я не знал о существовании этого проекта.

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

 
« Пред.   След. »
Полезные материалы по сходным темам
BannerFans.com