英文:
Documenting command in Doxygen
问题
我已经在C++中创建了一个简单的库，并且在Doxygen中非常好地记录了API。包中有一些示例程序可以使用该库。是否有一种方法可以在相同的Doxygen进程中记录这些（作为命令行程序）？
英文:
I have created a simple library in C++ and have with pretty good discipline documented the API in Doxygen. There are a few example programs to use the library in the package. Is there a trick to documenting those (as command-line programs) in the same Doxygen process?
答案1
得分: 3
我已决定在我的评论中添加一些更多详细信息的答案。
正如我在评论中提到的，我通常使用Doxygen的“MainPage”功能。
对于我的公共存储库，我使用README.md页面，并配置Doxygen如下：
OUTPUT_DIRECTORY = docs/
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_PRIV_VIRTUAL = YES
EXTRACT_PACKAGE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
INPUT = README.md <任何其他文件或目录>
USE_MDFILE_AS_MAINPAGE = README.md
然后这将生成Doxygen的HTML文件，可以在这里查看（请原谅我这个厚颜无耻的宣传）。
这对于提供库的一般概述、用例，特别是在你提到的情况下，应用程序参数、开关等非常有用。
编辑 2023-01-10：
如在此答案下的评论中所提到的，这绝不是实现 OP 目标的唯一方法。
如果要记录单独的文件（即可执行文件），可以轻松地将它们添加到Doxyfile中，如下所示：
# 单独的文件
INPUT = lib/include/myheader.hpp lib/src/myimpl.cpp examples/dosomethingcool.cpp
# 目录
INPUT = lib/include/ lib/src/ examples/
FILE_PATTERNS = *.cpp *.hpp
在你的示例实现中，你可以添加一个简单的JavaDoc风格的头注释：
/**
* @file myimpl.cpp
* @author Your Name <you@you.net>
* @date 2023-01-01
*
* @brief 包含一个实现/使用我的精彩库的示例。
*
* 在这里输入你的参考实现的详细说明。
* 你还可以包括Markdown，以便创建简单的表格，
* 或以你喜欢的方式格式化文本。
*
* 或者，你还可以添加一个使用代码的示例。
* @code{.sh}
* # 这样调用我的实现：
* ./myimpl -LgTz100
* @endcode
*
* # 参数的完整列表：
* | 长选项 | 短选项 | 描述 |
* |----------|-----------|-----------------|
* | -foo | -f | 执行某些操作 |
* | -bar | -B | 处理巴洛兹 |
*/
#include <iostream>
/**
* @brief 程序入口点。
* 你可以继续在这里进行正常的文档编写。
*
* @param argc 传递的参数总数
* @param argv 传递给应用程序的字符串参数
*/
int main(int32_t argc, char** argv) {
// 在这里实现任何操作
}
英文:
I've decided to add an answer to my comments with some more details.
As mentioned in my comments, I typically use the "MainPage" functionality of Doxygen.
For my public repositories, I use the README.md page and configure Doxygen as follows:
OUTPUT_DIRECTORY = docs/
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_PRIV_VIRTUAL = YES
EXTRACT_PACKAGE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
INPUT = README.md <any other files or directories>
USE_MDFILE_AS_MAINPAGE = README.md
And then this generates the Doxygen HTML files and can be seen here, for example (excuse the shameless plug)
It's useful for providing a general overview of your library, use-cases and especially in your mentioned case, app arguments, switches, etc.
Edit 2023-01-10:
As mentioned in the comments under this answer, this is certainly not the only way of achieving OP's goal.
If separate files (i.e. the executables) are to be documented, they can easily be added to the Doxyfile as such:
# individual files
INPUT = lib/include/myheader.hpp lib/src/myimpl.cpp examples/dosomethingcool.cpp
# Directories
INPUT = lib/include/ lib/src/ examples/
FILE_PATTERNS = *.cpp *.hpp
In your example implementation, you can then add a simple JavaDoc-style header:
/**
* @file myimpl.cpp
* @author Your Name <you@you.net>
* @date 2023-01-01
*
* @brief Contains an example of implementing/using my awesome library.
*
* Enter a detailed description of your reference implementation here.
* You may also include Markdown, so you can create simple tables,
* or format your text in a way that you like.
*
* Alternatively, you could also add an example using code.
* @code{.sh}
* # call my implementation like this:
* ./myimpl -LgTz100
* @endcode
*
* # A complete list of arguments:
* | Long opt | short opt | Description |
* |----------|-----------|-----------------|
* | -foo | -f | Foos something |
* | -bar | -B | Bars the baz |
*/
#include <iostream>
/**
* @brief Program entry point.
* You can continue with normal documentation here.
*
* @param argc The total amount of args passed
* @param argv The string arguments passed to the application
*/
int main(int32_t argc, char** argv) {
// implement whatever here
}
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论