C语言 在 C 中使用 Doxygen 记录变量
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2064871/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Documenting variables with Doxygen in C
提问by Pieter
Code:
代码：
#include <stdio.h>
/*
* \var int iOne
* \brief Integer 1
*/
/*
* \var int iTwo
* \brief Integer 2
*/
/*
* \var int iThree
* \brief Integer 3
*/
/**
* \brief Imitates a sheep.
*/
void sheep();
/**
* \brief Main function for test code
*/
int main() {
int iOne, iTwo, iThree;
iOne = 1;
iTwo = 2;
iThree = 3;
printf("%d %d %d", iOne, iTwo, iThree);
return 0;
}
void sheep() {
printf("Meeeh");
}
This doesn't generate descriptions for iOne, iTwoand iThreealthough that was my intention. How do I fix this?
这不生成描述iOne，iTwo并且iThree虽然这是我的本意。我该如何解决？
回答by Richard
DOxygen was made to document classes and function headers or, in other words, the interface. Think of the documentation as something that other programmers study in order to use your classes and functions properly. You shouldn't use DOxygen to document your implementation. Instead, document your local variables in the source with //or /* */.
DOxygen 被用来记录类和函数头文件，或者换句话说，接口。将文档视为其他程序员为了正确使用您的类和函数而研究的东西。你不应该使用 Doxygen 来记录你的实现。相反，使用//或 记录源中的局部变量/* */。
There are a number of ways to make comments in DOxygen, some examples of which (for member variables) can be seen in the manual here. I've copied them below.
在 DOxygen 中可以通过多种方式进行注释，其中一些示例（对于成员变量）可以在此处的手册中看到。我在下面复制了它们。
int var; /*!< Detailed description after the member */
int var; /**< Detailed description after the member */
int var; //!< Detailed description after the member
//!<
int var; ///< Detailed description after the member
///<
int var; //!< Brief description after the member
int var; ///< Brief description after the member
回答by Nick Meyer
You need to open your comments as Doxygen comments with /**.
您需要将您的评论作为 Doxygen 评论打开/**。
It may be clearer to do this, though:
不过，这样做可能更清楚：
int main() {
/** \brief Integer 1 */
int iOne;
/** \brief Integer 2 */
int iTwo;
/** \brief Integer 3 */
int iThree;
/** ... and so on ... */
}
This way you can change the name of the variable without breaking your documentation and it's also easier on other programmers who need to read your source code because the description of the variable is located next to it, not somewhere else in the file.
通过这种方式，您可以在不破坏文档的情况下更改变量的名称，并且对于需要阅读源代码的其他程序员来说也更容易，因为变量的描述位于它旁边，而不是文件中的其他位置。
