Система документирования ПО DOC++ - Форматирование справочника

Форматирование справочника

1. Введение

Система автоматизированного документирования DOC++ имеет средства форматирования, основанные на командах L^AT_EX. Например, команды "\bf", "\it", задающие свойства шрифта, команда переноса строки "\\". Полный список поддерживаемых команд представлен ниже:

Команда	Использование
$...$	Математический режим для строчных формул.
`\`#	Вывести символ `#''
`\`_	Вывести символ ```_`''
`\`	Вывести символ `` ''
`\`em	```{\em ...}`'' или ```\emph{...}`''
`\`bf	```{\bf ...}`'' или ```\textbf{...}`''
`\`it	```{\it ...}`'' или ```\textit{...}`''
`\`tt	```{\tt ...}`'' или ```\texttt{...}`''
`\`tiny	```{\tiny ...}`''
`\`scriptsize	```{\scriptsize ...}`''
`\`footnotesize	```{\footnotesize ...}`''
`\`small	```{\small ...}`''
`\`large	```{\large ...}`''
`\`LARGE	```{\LARGE ...}`''
`\`huge	```{\huge ...}`''
`\`Huge	```{\Huge ...}`''
`\`HUGE	```{\HUGE ...}`'
`\`hline	```\hline`''
Окружения T_EX'a:
center	```\begin{center} ... \end{center}`''
flushleft	``\begin{flushleft} ... \end{flushleft}`''
flushright	```\begin{flushright} ... \end{flushright}`''
verbatim	``\begin{verbatim} ... \end{verbatim}`''
tabular	``\begin{tabular}{lll} ...&...\\ ... \end{tabular}`''
array	```\begin{array}{lll} ...&...\\ ... \end{array}`''
itemize	```\begin{itemize} \item ... ... \end{itemize}`''
enumerate	```\begin{enumerate} \item ... ... \end{enumerate}`''
description	```\begin{description} \item[...] ... ... \end{description}`''
equation	```\begin{equation} ... \end{equation}`''
equation array	```\begin{eqnarray} ... \end{eqnarray}`''

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

2. Перекрестные ссылки

Перекрестные ссылки используются для включения в раздел гиперссылки на смежный или уточняющий раздел справочника. Ссылка на раздел справочника задается при помощи поля @see <список разделов справочника через пробел> в описании раздела.
Например:
/**
* @name section1
* @memo Short description
* @author A.V.Lunacharsky
* @see section2 section3
*/
Указывает DOC++ вставить ссылки на разделы с именем section2 и section3 в описании раздела Section1.

В примере:
/**
Функция fopen открывает файл с именем path и связывает его с потоком.
@memo Функция для открытия потоков
@return указатель на открытый файл, либо NULL.
@param path имя файла
@param mode - режим работы с файлом
@see getchar feof
*/
в описание функции fopen будет включен дополнительный раздел "See also:" в котором будут помещены ссылки на описание функций getchar() и feof().
Для того, чтобы сделать ссылку на раздел справочника, нужно прописать в поле @see список имен разделов, на которые будет сделана ссылка.
Имя раздела определяется DOC++ автоматически или может быть задано пользователем. Для того, чтобы задать имя раздела вручную, его нужно прописать в поле @name, например:
/**
Функция fopen открывает файл с именем path и связывает его с потоком.
@name fopen_func
@memo Функция для открытия потоков
*/
задает для раздела справочника, описывающего функцию fopen, имя fopen_func. Если не в описание данного раздела не включать поле @name, то DOC++ подставит имя автоматически. В данном случае, это будет "fopen".

3. Задание

3.1. Описать сложные структуры и функции вашей программы (см. семестровое задание) при помощи элементов форматирования. Описать поля каждой структуры данных при помощи таблицы со столбами ("Имя поля", "Семантика").