Основные структурные элементы
1. Введение
В простейшем случае doc++ используется следующим образом:
docxx <список файлов>
где "Список файлов" - набор документируемых файлов, имеющих специальную структуру:

1. Описание раздела
/**
 * ... Список полей
 */

2. Список подразделов
/*@{*/
Набор подразделов документа и их описание
/*@}*/

Описание раздела находится внутри специальных комментариев /** и */ либо ///.
Раздел описывается с помощью набора полей вида @<имя поля> <значение>, например:
/**
 * @name section1
 * @memo Short description
 * @author A.V.Lunacharsky
 * @see setion2 section3
 */

Например, если мы имеем следующий файл string.h, оформленный по правилам DOC++:

/**
@memo Набор стандартных строковых функций
@name  string.h
@author А.В. Автор2
@version 1
*/
/*@{*/

/**
Функция strcpy() копирует строку, указанную как src (включая завершающий символ `\0'), в массив, указанный как dest. Строки не могут перекрываться, и в целевой строке dest должно быть достаточно места для получения копии.
@memo копирование строки произвольной длины
*/
char *strcpy(char *dest, const char *src);

/**
Функция strncpy работает подобным образом, но копируются только первые n байт строки src. Таким образом, если нулевой байт отсутствует в первых n байтах src, то результирующая строка не будет завершена символом `\0'.
В случае, если длина src меньше, чем n, то остаток dest будет заполнен нулями. 
@memo копирование части строки

*/
char *strncpy(char *dest, const char *src, size_t n);

/*@}*/

и выполним команду:
docxx string.h
то получим следующий результат.

Здесь раздел верхнего уровня - файл string.h. Его описание идет в начале файла в комментариях /** и */. Далее следует команда /*@{*/, которая указывает на то, что за ней следует список подразделов и их описание. Для каждого подраздела DOC++ создаёт отдельный html-документ, в котором будет содержаться описание подраздела. В головном разделе помещается только его описание, список подразделов (в виде гиперссылок на html-файлы) и краткое описание каждого подраздела. Команда /*@}*/ указывает на то, что описание подразделов завершено.
На выходе получаем каталог html со следующей файловой структурой:
-> index.html - описание головного раздела (string.h) и ссылки на подразделы с кратким описанием.
-> strncpy.html - подраздел. описание функции strncpy.
-> strcpy.html - подраздел. описание функции strcpy.
-> toc.html - указатель по разделам.
-> general.html
-> icon1.gif
-> icon2.gif

Описание раздела (подраздела) состоит из набора полей. Полный список стандартных полей, описывающих раздел, приведен в табл. 1. Некоторые поля заполняет пользователь, некоторые поля DOC++ заполняет автоматически, осуществляя разбор исходного кода. Ни одно из полей при описании раздела не является обязательным.

Табл. 1. Список стандартных полей, описывающих раздел справочника.
Имя поля Заполняет Описание
@type DOC++ зависит от языка программирования.
@name оба зависит от языка программирования. В языке C - имя раздела. Позволяет ссылаться на данный раздел
@args DOC++ зависит от языка программирования.
@memo Пользователь краткое описание
@doc Пользователь подробное описание
@return Пользователь возвращаемое функцией значения
@param Пользователь параметр функции
@exception Пользователь описание исключений, порождаемых функцией
@see Пользователь список перекрестных ссылок
@author Пользователь список  авторов
@version Пользователь версия документа

Первые три поля из табл. 1. зачастую заполняются автоматически DOC++. Заполнение данных полей зависит от типа раздела, который определяется исходным кодом, следующим за  описанием данного раздела.
DOC++ поддерживает следущие типы разделов:

Тип раздела @type @name @args
Макрос #define name список аргументов макроса
Переменная Type name -
Функция/метод Return type name список аргументов функции и список исключений
Объединение/перечисление union/enum name -
Класс/структура class/struct name список потомков
Интерфейс interface name расширенные интерфейсы

Т.о., если имеем раздел:
/**
 * @name section1
 * @memo Short description
 * @author A.V.Lunacharsky
 * @see section2 section3
 */
int postmaster(int arg1, void* arg2)

то DOC++ выполнит разбор функции, выделит имя функции, возвращаемые значения и её аргументы.
2. Включение файлов
Зачастую в документируемой программе имеется большое количество файлов, обрабатываемых при помощи DOC++. В таком случае общепринятой практикой является использование команды @include: <имя файла>, которая указывает DOC++ включить  файл, переданный команде @include в качестве параметра как подраздел текущего раздела.
В таком случае формируется головной файл, содержащий описание справочника и набор команд @include, указывающих на файлы, описывающие разделы справочника.
Рассмотрим пример. Пусть у нас имеется две стандартные библиотеки языка C - string и stdio. Необходимо задокументировать функции данных библиотек и объединить под одним заголовком. В таком случае, можно создать один файл, представляющий собой головной раздел и содержащий набор директив @include, указывающих на файлы с DOC++-описанием библиотек string и stdio. Такой заголовочный файл может выглядеть следующим образом:

Файл index.txt
/**
Справочник по функциям библиотек stdio и string.
@memo Справочник по функциям
@author (c) 2004-05 А.В. Автор, А.В. Автор2
@version 1.0 от \today
*/

/*@{*/

/*@Include: stdio.h */
/*@Include: string.h */

/*@}*/

Тогда команда создания справочника может выглядеть следующим образом:
docxx index.txt
а результат получим примерно такой.
3. Типичные приемы использования
Обычно программа состоит из большого количества файлов:
  • Заголовочные файлы (*.h) - файлы, в которых описывается интерфейс модуля.
  • Исходные файлы (*.с) - файлы, содержащие реализацию функций и классов.
В таком случае, зачастую, для формирования справочника по функциям,  с помощью комментариев DOC++ оформляют заголовочные файлы программы. На вход DOC++ подаются только заголовочные файлы.  В таком случае в .c-файлы комментарии к функциям просто копируются из заголовочных файлов. Комментарии же к исходному коду указываются произвольным образом, в соответствии с потребностями программиста и в справочник не идут.
4. Задание
4.1. Разработайте модульную структуру вашей программы (см. семестровое задание). Для каждого модуля разработайте h-файл, содержащий список экспортируемых констант, переменных и функций. Выполните документирование вашей программы: оформите каждый h-файл в соответствии со стандартом DOC++, сгенерируйте html-документацию вашей программы.
Каждый раздел должен иметь описание и включать следующие поля:
  • имя раздела.
  • автор.
  • версия документа.
  • краткое описание.
Каждая функция должна к тому же включать следующие поля:
  • список параметров.
  • возвращаемое значение.
  • детальное описание функции.
5. Контрольные вопросы
  1. Можно ли документировать файлы с расширением *.inc, *php?
copyright © кафедра «Системное программирование»