Документировать программу, используя Doxygen?

Question

Мы используем Doxygen для документирования нашего API библиотеки C/C++. Это отличная работа. Проект также создает тестовую программу общего назначения, аналогичную командеили gpg. Я хотел бы документировать команды тестовой программы, используя Doxygen, потому что она помогает пользователям и обеспечивает согласованность документации (включая стиль).

Проблема, с которой я столкнулась, не может понять, как документировать программу (выходной артефакт, а не исходные файлы). Сообщение списка рассылки, Understanding how Doxygen Documentation is generated, указывает, что Doxygen не поддерживает документацию программы из коробки, но сообщение немного устарело. В потоке указано использование обработки XML и XSLT для документирования программы, но это все, что она заявляет. Он не предлагает ничего относительно того, как это сделать.

Как получить Doxygen для создания выделенной страницы для myprog.exe и документировать подкоманды и их аргументы? Что я могу использовать вместо первоклассной поддержки? Или как мы используем XML и XSLT, как указано в сообщении списка рассылки?

---

Я рад создать отдельную HTML-страницу. В этом случае, мне нужно знать, как интегрировать его так применяется стиль Doxygen и индексируется

Doxygen special commands страница выглядит много как то, что я хочу, но я не могу найти документацию по производству страницы нравится. (Предполагается, что они используют Doxygen для создания страницы).

---

$ doxygen --version 
1.8.9.1 

Answer 1

Я не уверен, если я понимаю ваш вопрос. Я предполагаю, что вы хотите создать новую страницу в документации, на которой вы можете описать использование вашей программы (что-то вроде руководства пользователя). Я думаю, вы должны больше узнать о командах @mainpage, @page, @section и @subsection.

Одна вещь, которую вы можете сделать, - создать дополнительный текстовый файл с именем «Usage.dox». В этом файле вы можете создать дополнительную страницу для описания использования программы вы документирующая, например:

/////////////////////////////////////////////////////////////////////////////// 
/// @page usage Usage of the Software 
/// 
/// @section Calling in the command line mode 
/// 
/// The usage of this software is as follows: 
/// 
/// <c>myProgram.exe [param1] [param2]</c> 
/// 
/// where for the first parameter the following is possible: 
/// 
/// | Parameter | Description   | 
/// |-----------|-----------------------| 
/// | -c  | Open the config mode. | 
/// | -s  | bla bla.    | 
/// 
/// @subsection Detailed description of the arguments 
/// 
/// ___ 
/// @subsubsection arg1 
/// Any detailed description of the argument arg1. 
/// ___ 
/// 
/// @subsubsection arg2 
/// Any detailed description of the argument arg2. 
/// ___ 
/// 
/////////////////////////////////////////////////////////////////////////////// 

Далее вы можете (если вы еще не сделали) создать файл «MainPage» который содержит информацию, указанную в файле «index.html», и установите ссылку на новую страницу. Таким образом, вы можете создать файл «MainPage.dox», содержащий:

/////////////////////////////////////////////////////////////////////////////// 
/// @mainpage Introduction 
/// 
/// Any text. 
/// 
/// For a description of the usage of this program see page @ref usage 
/// 
/// Any text. 
/////////////////////////////////////////////////////////////////////////////// 

Как вы можете видеть, я ссылку на странице под названием «Использование» (с помощью команды @ref), который я определил ранее в файле «Использование .dox». В результате создается ссылка на странице index.html, которая ссылается на новую страницу «Использование». Далее этот файл указан в разделе «Связанные страницы».

Вы также должны узнать больше о «оповещении» для doxygen.

Надеюсь, это даст вам направление.