Инструменты и цели

GNOME API документация выполняется с использованием пакета gtk-doc, который решает две основные задачи. Первая, автоматизирует создание основной документации API из исходного кода и комментариев. Вторая, позволяет людям легко изменять и дополнять автоматически сгенерированную документацию без редактирования самого исходного кода.

Инструмет gtk-doc запускается не вручную: вы просто помещаете несколько строк в ваш Makefiles, а затем когда вы выполняете make install, создаётся набор шаблонов и документов. Если вы измените шаблоны, инструментарий включит эти изменения в документацию при следующей сборке.

Подсказка:
Модули libglade и gtk+ в GNOME CVS прекрасно демонстрируют методы разработки GNOME, включая использование gtk-doc.

Форматы файлов и требования

Окончательным форматом документов является DocBook XML, просто как пользовательская документация. Промежуточные шаблоны похожи на XML но имеют недопустимый формат XML документации.

Пакету gtk-doc требуются таблицы стилей DocBook и инструмент анализа opensp XML/SGML, а также Perl. Emacs пользователи могут найти очень полезным использование режима XSL который обеспечивает пакет xslide.

Как установить модуль для использования gtk-doc

Эта инструкция соответствует тексту в файле "setting-up.txt" из модуля gtk-doc в GNOME CVS. Предпологается что вы будете использовать automake и autoconf.

  1. Установите пакета gtk-doc. В зависимости от дистрибутива пакет будет называться gtk-doc, gtkdoc, или gtk-doc-tools.
  2. Создайте каталог в котором вы хотите сохранять документацию. В основном все используют каталог "docs/reference/".
  3. Отредактируйте файлы Makefile.am:
    • Вам нужны Makefile.am для каждого создаваемого каталога.
    • Перечислите все подкаталоги в разделе SUBDIRS.
    • Перечислите все дополнительные файлы в разделе EXTRA_DIST.
    • Если вы хотите использовать XML тэги в ваших блоках комментариев кода, добавьте эту строчку в ваш docs/reference/Makefile.am:
      MKDB_OPTIONS= --sgml-mode --output-mode=xml
         
      
  4. Отредактируйте ваш configure.in:
    • Добавьте строку GTK_DOC_CHECK(1.0) для вызова макроса gtk-doc.m4.
    • Убедитесь что вы добавили Makefile.am файлы в ваш configure.in, чтобы autotools нашли их при сборке.

Теперь, когда вы собираете программное обеспечение, API документация будет генерироваться автоматически в каталог docs/reference. Есть дополнительные опции которые вы можете использовать -- примеры вы можете посмотреть в libglade и gtk+.

Подсказка:
В проекте GNOME, основная документация разработчиков обычно сохраняется в каталоге "docs" проекта, а API документация в каталоге "docs/reference". Пользовательская документация обычно находится в каталоге "help".

Комментирование кода для автоматического производства документации

Когда вы собираете свой проект с помощью gtk-doc, специально отформатированные комментарии конвертируются в документацию. Что это за специальный формат?

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

Если вы используете emacs, вы можете добавить файл tools/gtk-doc.el в ваш файл .emacs, и использовать горячие клавиши C-x4h или M-x gnome-doc-insert для размещения правильной структуры комментария для вас.

Блок комментариев будет выглядеть так:

/**
 * function_name:
 * @par1:  описание параметра №1. Его можно расширить больше чем
 * на одну строку.
 * @par2:  описание параметра №2
 *
 * Здесь находится описание функции.
 *
 * Возвращает: целочисленное.
 */

Изменения в шаблонном файле распознаются каждый раз когда вы пересобираете документацию, но изменения для блока комментария нет. Чтобы заставить gtk-doc пересканировать код, удалите файлы *.stamp в каталоге откуда была вызвана gtk-doc, затем пересоберите.

Более детальные подсказки стиля смотрите в GTK Documentation Author Guidelines.

Синтаксис комментариев и XML

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

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

Организация вашей документации

По умолчанию, gtk-doc производит и структурирует документацию используя .h и .c файлы вашего проекта: каждый файл получает собственный раздел документации. Для регулирования заполнения структуры вам необходимо отредактировать файл myproject-sections.txt (название поменяйте на название вашего проекта, конечно).

Для начала нового раздела или подраздела вашего документа, поместите тэг <SECTION> и <SUBSECTION> на отдельную строку. Каждый раздел должен содержать набор связанных с ним деклараций функций или макросов, перечислений. Обычно, перечисление помещается после первой функции которая его использует.

Если у вас есть закрытые объекты которые вы не хотите описывать в документации, добавьте <SUBSECTION_private> в конец раздела где это необходимо. Окончательный вывод не будет содержать эту декларацию. Кроме того, когда вы в следующий раз выполните команду make templates, декларация также будет удалена из шаблонного файла.

XML синтаксис в шаблонных файлах

DocBook XML позволяет вам большую гибкость. Полное описание DocBook доступно docbook.org, но в основном вам потребуются несколько тэгов.

Подсказка:
Шаблонные файлы XML могут быть найдены в каталоге tmpl/. Если вы следовали указаниям по умолчанию GNOME, то это будет myproject/docs/reference/tmpl/.

Некоторые наиболее часто используемые тэги:

Подсказка:
Обычно, символы "больше" и "меньше" в блоках комментариев конвертируются в "&gt;" и "&lt;" в XML, для отображения как > и < в окончательном виде удобном для чтения. Для использования XML тэгов в ваших блоках комментариев, используйте --sgml-mode флаг в вашем Makefiles. Например, gtk+ использует строку MKDB_OPTIONS=--sgml-mode --output-format=xml, обозначая что когда генерируется DocBook, вывод в формате XML (по умолчанию) и ожидается обнаружение тэгов в блоках комментариев кода.