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).
5. Тепер залишилося перейти на закладку Run і натиснути на кнопку Run doxygen:
Якщо під час компіляції документації в текстах початкових кодів зустрінуться помилки, то вони будуть виведені в поле виведення "Output produced by doxygen". У повідомленнях вказані номери рядків, де знайдені помилки. Нумерація рядків у повідомленнях "tag without matching" може не збігатися з рядками, де ці помилки є насправді.
Запуск генерації документації можна також провести з командного рядка введенням команди (config-file ім'я файлу конфігурації doxygen):
Якщо конфігураційного файлу немає, то можна вручну згенерувати конфігурацію. Потрібно виконати, як мінімум, наступні кроки (для прикладу 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).
[Проблема правильної обробки кодування української мови]
# Раніше тут було зазначено 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.