Несмотря на то, что документирование исходных текстов представлено в Шаге 3, в новом проекте это должно быть конечно же шагом 1. Здесь я предполагаю, что у Вас уже есть некоторы код и Вы хотите использовать doxygen, чтобы получить хорошее описание интерфейса приложения и, может быть, также внутренней структуры.
Если опция EXTRACT_ALL установлена в NO в конфигурационном файле (по умолчанию), тогда doxygen будет только генерировать документацию для зарегистрированных элементов, файлов, классов и пространств имен. Так как же их задокументировать? Для элементов, классов и пространств имен существуют в две основные возможности:
- Поместить специальный документационный блок в начало декларирования или определения элемента, класса или пространства имен. Для элементов файла, класса и пространства имен также допустимо помещать описание непосредственно сразу после элемента. Смотрите раздел Специальные документационные блоки, чтобы узнать больше о специальных документационных блоках.
- Поместить специальный документационный блок куда-то еще (другой файл или другое место) и поместить структурную комманду в документационный блок. Структурная комманда связывает документационный блок с определенным объектом, который может быть задокументирован (например элемент, класс, пространство имен или файл). Смотрите раздел Документирование в произвольных местах, чтобы узнать больше о структурных коммандах.
Файлы могут быть документированы только вторым способом, так как невозможно разместить документационный блок перед фалом. Конечно, элементы файла (функции, переменные, определения типов (typedef), определения констант (define)) не нуждаются в подробных структурных коммандах; перед ними или после них могут быть размещены только специальные документационные блоки.
Текст внутри специально документационного блока анализируется перед его записью в HTML или/и файлы выгрузки.
Во время синтаксического анализа следующих шагов происходит следующее:
- Выполняются специальные команды в документации. Смотрите раздел Специальные комманды для просмтра всех комманд.
- Если строка начинается с нескольких пробелов следующих за одной или несколькими звездочками (
*) и затем прдолжается необязательными пробелами, то все пробелы и звездочки удаляются. - Все полученные пустые строки преобразуются в разделитель абзацев. Это позволяет сохранить Ваши вставки команд нового абзаца неизменными для получения удобочитаемой документации.
- Ссылки создаются для слов, соответствующих задокументированным классам (если слову не предшествует %; тогда слово не будет связано, и знак % будет удален).
- Ссылки для элементов создаются, когда определенные шаблоны найдены в тексте. Смотрите раздел Генерация автоматических ссылок для получения дополнительной информации о том, как работает Автоматическая генрация ссылок.
- # Html-тэги, которые находятся в документации, интерпретированы и преобразованы $ \mbox {\LaTeX} эквиваленты $ за $ \mbox {\LaTeX} вывод $. См. Команды HTML раздела для краткого обзора всех поддержанных html-тэгов. Html-тэги, которые находятся в документации, интерпретированные и преобразованные в эквивалентны для выходному формату . Смотрите раздел HTML команды для обзора всех поддерживаемых html-тэгов.