如何使用 Doxygen 记录 C++ 函数中的局部变量答案

【问题标题】：How to use Doxygen to document local variables within C++ functions如何使用 Doxygen 记录 C++ 函数中的局部变量
【发布时间】：2013-01-24 18:41:47
【问题描述】：

例如在我的函数中

//starting code with doxygen documentation
/** The main function. I will now try to document variables within this main function*/
int main()
{
 int arr[]; /** \brief an integer array*/
 .....
 return 0;
}
//end of code

但是，当我在配置文件中将“HIDE_IN_BODY_DOCS”变量设置为“NO”的情况下使用 Doxygen 时，这不会执行此局部变量的特定文档。相反，它只是将这一点与函数文档一起打印出来，就好像它是函数中的任何其他注释行一样

如何使用 Doxygen 记录这些局部变量？

【问题讨论】：

按照您的说法，记录这样一个变量的正确方法是什么？您看到的行为显然是documented。
我希望不会。文档是关于接口的。使用 cmets 了解实现细节。

标签： c++ documentation doxygen

【解决方案1】：

我不知道这样做的方法（而且我确实怀疑是否存在方法）。请记住，doxygen 是用来记录类和函数头的，即接口。将文档视为其他程序员为了正确使用您的类和函数而学习的东西。你不应该使用 doxygen 来记录你的实现。但是，当您使用 C(++) 进行编程时，在源代码中记录局部变量应该不是问题。只需给它一个正确的名称或“在源代码中”记录它：

Cat cats[]; // holds a bunch of cats

在定义所有变量的语言中，必须在函数的开头声明（Delphi、Pascal），但您需要的系统是有意义的。

【讨论】：

【解决方案2】：

虽然您可以将 cmets 放在函数体中，并让它们像这样作为函数文档的一部分出现

/** @file */

/** The main function. I will now try to document 
 *  variables within this main function.
 */
int main()
{
  /** an integer array. */
  int arr[];

  /** An endless loop */
  for (;;) {}

  return 0;
}

正如其他人已经指出的那样，通常不建议这样做。如果您想（作为开发人员）阅读源代码以及文档，您可以更好地在正文中使用普通 C cmets

/** @file */

/** The main function. I will now try to document 
 *  variables within this main function.
 */
int main()
{
  /* an integer array. */
  int arr[];

  /* An endless loop */
  for (;;) {}

  return 0;
}

同时将INLINE_SOURCES 设置为YES。

【讨论】：