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

Итак, процесс по шагам:

1. Качаем по ссылке [1], доступны версии для Linux i386, Mac OS X 10.6 (Snow Leopard), Mac OS X 10.4 (Tiger), Windows XP/Vista/7, а также исходники (Doxygen распространяется под лицензией GPL).

2. Запускаем doxygen-1.7.2-setup.exe. Отвечаем на несложные традиционные вопросы инсталлятора (можно тупо жать Next). После инсталляции появится папка c:\Program Files\doxygen\, где и находится вся система Doxygen, документация по ней, и утилиты.

3. Запускаем c:\Program Files\doxygen\bin\doxywizard.exe. Это программа, которая позволяет упростить создание и использование конфигурационного файла для создания документации (Doxygen GUI frontend).

4. Предположим, что нам нужно создать документацию к каким-то исходникам. В этом примере я буду делать документацию к проекту LUFA 100807\Demos\Device\ClassDriver\VirtualSerial\. Теперь нужно посмотреть, есть ли в каталоге с исходниками готовая конфигурация Doxygen. Обычно такой файл называется Doxygen.conf или Doxyfile, и имеет примерно такое содержание: "# Doxyfile 1.6.2 # This file describes the settings ...". В моем случае папка с исходниками VirtualSerial уже содержала готовый конфигурационный файл Doxygen.conf. Теперь в программе меню doxywizard.exe выбрать File -> Open... -> файл Doxygen.conf.

5. Теперь осталось перейти на закладку Run и нажать на кнопку Run doxygen:

Если во время компиляции документации в текстах исходников встретятся ошибки, то они будут выведены в поле вывода "Output produced by doxygen". В сообщениях указаны номера строк, где найдены ошибки. Нумерация строк в сообщениях "tag without matching" может не совпадать со строками, где эти ошибки имеются на самом деле.

Запуск генерации документации можно также провести из командной строки вводом команды (config-file имя файла конфигурации doxygen):

doxygen  

В моем примере в папке VirtualSerial\Documentation\html\ появятся файлы в формате html. Начинать просмотр документации нужно с файла VirtualSerial\Documentation\html\index.html.

Если конфигурационного файла нет, то можно вручную сгенерить конфигурацию. Нужно выполнить, как минимум, следующие шаги (для примера VirtualSerial):

Закладка Wizard -> Project:
- в поле "Step 1: Specify the working directory from which doxygen will run" указать путь до каталога проекта. В моем случае это c:\aaa2\LUFA 100807\Demos\Device\ClassDriver\VirtualSerial\
- в поле "Project name:" укажите имя проекта (LUFA Library - Virtual Serial Device Demo).
- в поле "Project version or id:" укажите версию проекта (0.0.0).
- в поле "Source code directory:" укажите ./
- в поле "Destination directory:" укажите ./Documentation/
- если Ваш проект содержит подпапки с исходниками, поставьте галочку "Scan recursiVely".

Закладка Wizard -> Mode:
- Select the desired extraction mode: -> All Entities.
- Select programming language to optimize the results for -> Optimize for C or PHP output

Закладка Wizard -> Output (выберем на этот раз формат RTF):
- убираем галочку HTML
- убираем галочку LaTeX
- ставим галочку Rich Text Format (RTF)

Закладка Wizard -> Diagrams:
- Diagrams to generate -> No diagrams

Закладка Run:
- нажимаем кнопку Run Doxugen. В результате получим файл единственный файл VirtualSerial\Documentation\rtf\refman.rtf.

Полученный файл конфигурации можно сохранить для дальнейшего использования (File -> Save as... -> Doxyfile).

[Проблема правильной обработки кодировки русского языка]

По умолчанию Doxygen генерирует html-текст в кодировке UTF-8 (используется мета-тег), и предполагает, что входной формат текста тоже UTF-8. С такими настройками поставляются большинство конфигов Doxygen. При попытке сгенерировать с таким конфигом html-документацию из текстового формата windows-1251 (с таком формате имеется большинство файлов исходников, содержащих русскоязычные комментарии), на выходе получается html-файл, который отображается всеми браузерами с кракозябрами. Эти кракозябры исчезнут, если вручную переключить браузер из кодировки UTF-8 в кодировку windows-1251. Это, конечно, не решение проблемы - возникает неудобство, так как необходимо постоянно переключаться в кодировку windows-1251. Заставить doxygen генерировать тег с charset=windows-1251 невозможно. Однако проблема фиксится довольно просто - достаточно в конфигурационном файле doxygen указать правильную кодировку входного файла - вместо кодировки UTF-8 указать кодировку windows-1251. Делается это правкой переменной конфига INPUT_ENCODING:

# раньше тут было указано INPUT_ENCODING = UTF-8
INPUT_ENCODING         = windows-1251

Кроме того, если нужно правильно распознать русский текст, который есть в файле Doxygen.conf (например, это может быть текст имени проекта PROJECT_NAME и другие строки), то необходимо отредактировать переменную конфига DOXYFILE_ENCODING (указать кодировку windows-1251):

# раньше тут было указано DOXYFILE_ENCODING = UTF-8
DOXYFILE_ENCODING      = windows-1251 

Вот так можно исправить кодировку через интерфейс GUI:

После такого исправления html будет корректно генерироваться, и правильно отображаться всеми браузерами, русский текст будет без кракозябр.

[Экранирование специальных символов doxygen] 

Для устранения предупреждений типа "имя_файла:номер_строки: warning: explicit link request to 'define' could not be resolved" нужно применять для экранирования спецсимволов обратный слеш '\' (backslash). Например, так нужно экранировать символ # вместе с ключевым словом define:

тут текст \#define тут дальше текст

Это устранит предупреждения типа request to '...' could not be resolved. 

[Ссылки]

1. DoxyGen Latest Release site:stack.nl - отсюда можно скачать бинарники и исходники Doxygen.
2. Проект LUFA 100807 -> Demos -> Device -> ClassDriver -> VirtualSerial, который использовался в статье (вместе с конфигами Dogygen и сгенерированной документацией).
3. Дистрибутив doxygen-1.7.2-setup.exe.