В двух последних статьях «Обратный инжиниринг исходного кода в диаграммы UML» и «Визуальная документация зависимостей Ant за 3 простых шага» мы увидели, насколько просто и полезно автоматизировать техническую документацию. Используя инструменты с открытым исходным кодом, мы легко смогли предоставить хорошую техническую документацию в течение нескольких минут и совершенно бесплатно. Мы также смогли поддерживать это в актуальном состоянии, добавляя дополнительные задачи в наши файлы сборки Ant, и запускали их с нашего CI Server (в нашем случае Hudson) при фиксации и ночных сборках, а также публиковали результаты.
В этой статье я покажу вам, как использовать еще один инструмент под названием Doxygenдля создания технической документации на основе вашего исходного кода. Мы все использовали Javadoc и использовали его долгое время, верно? Итак, вы можете спросить, зачем нужен другой инструмент, который производит ту же HTML-документацию? У Doxygen есть небольшое преимущество перед Javadoc, и вот несколько причин, почему вы должны рассмотреть возможность использования того же:
- С Javadoc вы должны помнить все HTML-теги, которые вы должны встроить в комментарии к коду. Тем не менее, с помощью кода Doxygen комментарии намного более лаконичны и полны, без необходимости какого-либо HTML.
- Doxygen также может генерировать различные диаграммы, некоторые из них мы рассмотрим позже.
- Doxygen также обеспечивает структурированное представление исходного кода. Как я уже упоминал в 2 выше в виде различных диаграмм, перекрестные ссылки и выделенный синтаксис кода.
- Вы получаете все вышеперечисленные преимущества, даже если в коде вообще нет комментариев.
- Наконец, что не менее важно, Doxygen — это система документации не только для Java, но и для различных других языков, таких как C ++, C, Java, Objective-C, Python, IDL (варианты Corba и Microsoft), Fortran, VHDL, PHP, C #.
Итак, не теряя больше времени, давайте посмотрим, что нам нужно для начала работы с Doxygen.
Шаг 1. Скачать, установить Doxygen.
Загрузите бинарный дистрибутив Doxygen для используемой операционной системы. Я скачал бинарный дистрибутив для Mac OS X под названием Doxygen-1.5.6.dmg . Установка очень проста, просто перетащите значок doxygen из этой папки в папку «Программы» или куда вы хотите ее сохранить; как показано. Я уронил его в папку «Приложения». Только не забудьте вспомнить, куда вы его перетащили Чтобы удалить, просто удалите файл. Это полностью автономно.
Шаг 2: Настройте Doxygen.
Чтобы сгенерировать документацию с использованием Doxygen, вам понадобится файл конфигурации, который называется Doxyfile. Вы можете создать этот файл двумя способами; либо с помощью мастера Doxygen, либо с помощью параметра командной строки. Давайте посмотрим, как использовать обе эти опции для создания файла конфигурации:
a. Командная строка. Откройте окно командной строки и введите следующее, как показано ниже:
Вы должны быть в состоянии найти файл конфигурации, созданный в вашей пользовательской папке по умолчанию. Файл выглядит так:
# Doxyfile 1.5.6
# Этот файл описывает настройки, которые будут использоваться системой документации
# doxygen (www.doxygen.org) для проекта
#
# Весь текст после хеша (#) считается комментарием и будет игнорироваться
# The формат:
# TAG = значение [значение, …]
# Для элементов списков можно также добавить, используя:
# TAG + = значение [значение, …]
# Значения, содержащие пробелы, должны быть заключены в кавычки («»)# ————————————————- —————————
# Параметры конфигурации, связанные с проектом
# —————— ————————————————— ——-# Этот тег определяет кодировку, используемую для всех символов в файле конфигурации
# что следует. По умолчанию используется UTF-8, который также является кодировкой, используемой для всего
текста # до первого появления этого тега. Doxygen использует libiconv (или
# iconv, встроенный в libc) для транскодирования. Смотрите
# http://www.gnu.org/software/libiconv для списка возможных кодировок.DOXYFILE_ENCODING = UTF-8
# Тег PROJECT_NAME — это одно слово (или последовательность слов, заключенная в
# в кавычки), которое должно идентифицировать проект.PROJECT_NAME =
# Тег PROJECT_NUMBER можно использовать для ввода номера проекта или редакции.
# Это может быть удобно для архивации сгенерированной документации или
#, если используется какая-либо система контроля версий.PROJECT_NUMBER =
б. Вариант мастера.
Запустите приложение Doxygen, и вы сможете создать файл конфигурации, используя подход мастера, как показано ниже.
Пользовательский интерфейс довольно интуитивно понятен, поэтому я собираюсь пропустить объяснение этого подробно.
Подход мастера был тем, который я использовал, чтобы получить начальные настройки для файла конфигурации. который вы всегда можете изменить позже.
Вот несколько параметров в моем файле конфигурации Doxygen:
# Doxyfile 1.5.6
# ——————————————— ——————————-
# Параметры конфигурации, связанные с проектом
# ————- ————————————————— ————
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = PetStore
PROJECT_NUMBER = 1.0
# ————————— ————————————————-
# Построить связанные параметры конфигурации
# ——————————————— ——————————
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
# ————————————————- —————————
# параметры конфигурации, связанные с выводом HTML
# ————— ————————————————— ———-
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
GENERATE_TREEVIEW = YES
Шаг 3. Doxygen и Ant.
Чтобы использовать Doxygen, нам нужна задача Ant. Уже есть задание Ant для Doxygen, которое вы можете скачать здесь .
Как всегда, после использования Mac, когда я скачал двоичные файлы и попытался их использовать, я получил очень известное сообщение об ошибке:
java.lang.UnsupportedClassVersionError: Неверный номер версии в файле .class
Итак, нужно было скачать исходный код, скомпилировать и собрать его. Скопируйте эту библиотеку в папку ваших проектов. Теперь давайте начнем вносить изменения в наш файл сборки.
3.a: Давайте определим задачу Doxygen.
<taskdef name="doxygen" classname="org.doxygen.tools.DoxygenTask" classpath="lib/ant_doxygen.jar" />
3.b: для генерации HTML документации:
<doxygen configFilename="reports/Doxyfile">
<property name="INPUT" value="${srcdir}" />
<property name="RECURSIVE" value="yes" />
</doxygen>
3.c: Позволяет объединить их в цель и запустить:
<target name="generate-doxygen-docs">
<taskdef name="doxygen" classname="org.doxygen.tools.DoxygenTask"
classpath="lib/ant_doxygen.jar" />
<doxygen configFilename="reports/Doxyfile">
<property name="INPUT" value="${srcdir}" />
<property name="RECURSIVE" value="yes" />
</doxygen>
</target>
[doxygen] Exec: /Applications/Doxygen.app reports / Doxyfile
BUILD FAILED
/CodeMetricsProject/build.xml:91: Doxygen не найден в переменной PATH.Общее время: 7 секунд
3.d: Итак, запускать Doxygen не по пути .
мы вносим изменения в задачу doxygen, как показано ниже:
<doxygen doxygenPath="/Applications/Doxygen.app/Contents/Resources/doxygen" configFilename="reports/Doxyfile">
Давайте снова запустим цель и посмотрим, исправит ли она все. Да, действительно.
generate-doxygen-docs:
[doxygen] Exec: /Applications/Doxygen.app/Contents/Resources/doxygen reports / DoxyfileBUILD SUCCESSFUL
Общее время: 8 секунд
4. Интеграция с Гудзоном.
4.a Изменить Hudson Job.
Если у вас работает цель Ant, вызов этого с вашего CI-сервера становится тривиальным. В Hudson выберите свое задание, нажмите на configure и добавьте эту новую цель, которая будет вызываться при запуске сборки.
4.b Опубликовать отчеты.
4. c: Образцы отчетов.
Запустите сборку и детально посмотрите на отчеты, сгенерированные Doxygen, как показано ниже:
I have given you a brief overview of Doxygen in this article, how to configure the same, and use it effectively to generate technical documentation on a continuous basis; either on commit builds or nightly builds. The Doxygen web site has lots of information on how to use it with other programming languages and also has tutorials in languages other than English as well.
As always, if you are having trouble getting Doxygen to work, leave a comment or check out the Doxygen web site.