http://youinf.ru/imgs/doxygen.jpg

Создание документации из исходных кодов

Щёлкните по любому подразделу для его раскрытия-закрытия Раскрыть все подразделы меню

Введение в Doxygen

Автодокументирование с помощью Doxygen

Doxygen — это кроссплатформенная система документирования исходников, которая поддерживает языки: C/C++, Obj-C, Python, Java, IDL, PHP, C#, Fortran, TCL и VHDL.

Doxygen обеспечивает автодокументирование путем обработки спецкомментариев, размещаемых в исходном коде.

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

Де-факто Doxygen стал основным, определяющим стандартом документирования из аннотированных C/C++ исходников. Фактически система работает как компилятор, анализируя спецкомментарии и создавая из них документацию.

Документация извлекается непосредственно из исходного кода, что в дальнейшем значительно упрощает сопровождение, хранение и обновление документации проекта.

Имплементация Doxygen подразумевает внедрение специального синтаксиса, который используется для оформления блоков с комментариями.

Синтаксис Doxygen следует применять для формирования шапок файлов, написания заголовков функций и методов, внутренних комментариев и прочего.

Обычные Си комментарии, превращаются в документацию путем инъекции в текст специальных тегов, которые указывают Doxygen, что комментарии написаны для него.

В результате, для создания документации достаточно просто писать комментарии в коде, придерживаясь нескольких простых правил.

Для многострочного комментария используется конструкция:
/** ваш комментарий */

Для однострочного комментария используется конструкция:
/// ваш комментарий

Иногда нужно расположить комментарий после, либо на одной строке с описываемым элементом.

Пример:

Отметим, что Doxygen позволяет формировать документацию в нескольких форматах:
HTML (генерация онлайн документация для WEB браузеров )
XML
RTF
MAN
LATEX

Также вывод может быть легко конвертирован в CHM, PostScript и PDF формат.

Doxygen портирован на все популярные операционные системы: Mac OS, Linux, Unix и Windows.

Вывод Doxygen может содержать в себе таблицы, списки, ссылки, диаграммы, графы, иерархические указатели и т.п.

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

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

Документирование кода функций и методов с помощью Doxygen

Документирование функций и методов

Для описания методов и функций используются следующие основные теги:

@arg
Описание параметров, передаваемых функции.

@brief
Краткое описание сущности.

@detailed
Подробное описание сущности.

@example
Указывает, что блок комментариев содержит пример использования чего-либо.

@internal
Указывает, что фрагмент предназначен только для внутреннего использования

@param
Описание параметров, передаваемых функции.

@pre
Начальные условия

@post
Конечные условия

@return
Описание значения, возвращаемого функцией.

@retval
Для более подробного описания возвращаемых значений

@see
Ссылки на классы, функции, методы, переменные, файлы, URL и пр.

В результате документирования функции получаем примерно следующее:

Чтобы привести пример работы используется конструкция @code – @endcode:

Документирование файлов с помощью Doxygen

Список команд документирования файлов:

@mainpage
Используется для указания основной (начальной) страницы проекта
Пример: @mainpage Главная страница

@page
Служит для указания дополнительного раздела документации
Пример: @page page1 – Страница 1

@ref
Используется для указания ссылок на другие страницы документации
Пример: @ref page1

@file
Краткое описание файла
Пример: @file file.h

@author
Служит для указания автора
Пример: @author Ivanov I.I.

@date
Дата написания файла
Пример: @date February, 2014

@defgroup
Задаёт группу в большом проекте для разделения на подпроекты.
Пример: @defgroup group – Админы

@version
Используется для указания версии

В результате для описания файла проекта используем следующий блок команд:

Описание групп в Doxygen

Описание групп в Doxygen

@name
Описание группы чего-либо одним комментарием.

Пример:

/@ {
/// @name Функции инициализации / деинициализации

//@ }

Замечания в Doxygen

Ремарки в Doxygen

Для добавления замечаний в код используются следующие команды/теги:
@attention
@bug
@todo
@note
@warning

Имя команды определяет тип замечания/ремарки, и каждая команда вставляет соответствующую заметку. Для них Doxygen формирует отдельные списки, по которым можно быстро найти нужное место в коде.

Примеры:

Другие команды Doxygen

Другие интересные команды

@class :
Описание класса

@struct :
Документирует структуру

@union :
Документирует объединение

@enum :
Документирует перечисление

@fn :
Документирует функцию

@var :
Документирует переменную

@def :
Документирует макрос

@namespace:
Документирует пространство имен

@typedef :
Документирование объявления типа

@interface:
Документирование интерфейса

@package :
Документирование пакета

Настройка Doxygen

Настройка Doxygen

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

Теги, хранящиеся в конфигурационном файле, описывают внешний вид документации, какие сущности и отношения между ними следует в неё включать, имя проекта, путь к анализируемым файлам и т.п.

Конфигурационный файл достаточно настроить один раз под свои потребности и затем в новых проектах изменять лишь один тег – PROJECT_NAME.

Ниже показаны наиболее интересные теги конфигурационного файла:

Тегов настройки у Doxygen более чем достаточно. Чтобы облегчить работу можно выполнить команду: doxygen -g и конфигурационный файл с именем Doxyfile будет создан автоматически.

Doxyfile содержит настройки по умолчанию. Вы можете изменить их под свои нужды. Это сделать довольно просто благодаря содержащимся в Doxyfile пояснениям.

Запуск Doxygen

Запуск Doxygen

Запуск системы автодокументирования очень прост – для этого надо запустить Doxygen указав ему путь к конфигурационному файлу:

В зависимости от настроек будут созданы html, rtf, latex, xml, man каталоги в директории выгрузки. Как подсказывают названия, эти каталоги содержат сгенерированную документацию в HTML, RTF, LaTeX, XML и Unix-Man Page форматах.

По умолчанию, директория выгрузки – это каталог из которого запущен Doxygen. Путь к директории выгрузки, может быть изменен в конфигурационном файле с помощью тега OUTPUT_DIRECTORY

Формат конкретного каталога с документацией в директории выгрузки может быть выбран с использованием тегов: HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, XML_OUTPUT и MAN_OUTPUT

Если OUTPUT_DIRECTORY не пуст, а такой директории выгрузки не существует, Doxygen создаст её для Вас.

Вывод в HTML

Вывод в HTML

Для того, чтобы просмотреть сгенерированную HTML документацию нужно указать в адресной строке браузера путь к файлу index.html в каталоге html. Для получения лучших результатов, браузер должен поддерживать CSS.

Некоторые из возможностей, такие как GENERATE_TREEVIEW, требуют браузер, который поддерживает DHTML и Javascript.

Если Вы планируете использовать средства поиска (см. SEARCHENGINE), то просматривайте HTML вывод через WEB-сервер поддерживающий PHP (пример, Apache с предустановленным PHP модулем).

Вывод в RTF

Вывод в RTF

Doxygen объединяет вывод в RTF в один файл с именем refman.rtf. Этот файл оптимизирован для импорта в Microsoft Word.

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

Вывод в LaTeX

Вывод в LaTeX

В первую очередь, для получения LaTeX документации необходимо скомпилировать сгенерированную Doxygen‘ом документацию компилятором LaTeX. Для упрощения процесса компилирования сгенерированной документации, Doxygen записывает Makefile в каталог latex.

Содержание и цели в Makefile зависят от значения тега USE_PDFLATEX.

Если тег USE_PDFLATEX установлен в NO), то выполнив make без аргументов в каталоге latex будет сгенерирован dvi файл, вызывающий refman.dvi. Этот файл может быть просмотрен с помощью xdvi или сконвертирован в PostScript файл refman.ps путем запуска make ps (это требует наличия dvips).

Чтобы разместить 2 страницы на одной физической странице используйте make ps_2on1. Результирующий PostScript файл может быть отправлен на PostScript принтер. Если у Вас нет PostScript принтера, Вы можете попытаться использовать ghostscript, чтобы сконвертировать PostScript в формат который понимает Ваш принтер.

Конвертирование в PDF формат возможно если установлен интерпритатор ghostscript.

Для генерации документации в формате PDF выполните make pdf (или make pdf_2on1). Будет построен файл refman.pdf.

Если тег USE_PDFLATEX установлен в YES), то для конвертирования вывода в формат PDF достаточно запустить make без аргументов или make pdf_2on1.

Чтобы получить более наглядный PDF файл, можно установить тег PDF_HYPERLINKS.

Вывод в XML

Вывод в XML

XML вывод состоит из кучи структурированной информации, собранной Doxygen. Каждой структуре class/namespace/file/... соответствует свой собственный XML файл и индексный файл с именем index.xml.

Также генерируется файл с именем combine.xslt ( XSLT script), который может быть использован для объединения всех XML файлов в один файл.

Doxygen также генерирует два файла-схемы XML: index.xsd (для индексного файла) и compound.xsd (для файлов со структурой).

Этот файл-схема описывает возможные элементы, их атрибуты и как они структурированы, то есть он описывает грамматику XML файлов и может быть использован для проверки или управления XSLT скриптами.

В каталоге addon/doxmlparser Вы можете найти библиотеку парсера для чтения XML выгрузки (см. addon/doxmlparser/include/doxmlintf.h для получения интерфейса к библиотеке).

Вывод в Man

Вывод в Man

Сгенерированные страницы man могут быть просмотрены с помощью программы man. Вым нужно убедиться, что директория с man файлами прописана в пути (смотрите переменную окружения MANPATH). Заметим, что существуют некоторые ограничения возможностей формата man page, в следствие чего некоторые данные (такие как диаграммы классов, перекрестные ссылки и формулы) будут утеряны.

© Копировать пост можно лишь при наличии прямой индексируемой ссылки на youinf.ru

  

 

1 Комментарий

  1. among:

    Hey there just wanteⅾ to ɡive you a quick heads up
    and let уou know a few of the imageѕ aren’t loading properly.

    I’m not sure why but I think its a linking issue.
    I’ve tried it in two different internet browsers and botһ
    show the same օutcome.

    Голосовать: Thumb up 0 Thumb down 0

Оставьте Комментарий

 



 

Comment Spam Protection by WP-SpamFree

Trackbacks

 
 

Яндекс цитирования