请推荐 doxygen 快捷方式

Question

我必须用 C 编写一些代码，所以我决定学习 doxygen（和颠覆）。

我希望我的文档简明扼要且合理无冗余。 Best Tips for documenting code using doxygen? 很有帮助，但还不够。我需要反冗余建议。

在某处有等效的 doxygen 缩写的参考列表吗？有时似乎需要一个完整的关键字，有时似乎是推断出来的。

 /*! \fn int main(int argc, char *argv[])
  *  \brief the main function prototype
  *  \param argc  a counter to arguments
  *  \param argv  the arguments
  *  \return the program exit code
  */
 int main(int argc, char *argv[])

其他地方

 /*! \fn int main(int argc, char *argv[])
  *  \details long explanation is that I just return 0
  *  \seealso main prototype
  */
 int main(int argc, char *argv[]) { return 0; }

有很多冗余需要检查修订。我发现了一些捷径，但这是随机的。上述线程中的一些人声称不需要 \file，doxygen 手册建议全局变量有时需要它。 /*!

Answer 1

所以，这是我为减少 doxygen 名称冗余而进行的实验：

//! \file test.h  our very lonely .H file 

/*!
 * the file statements above are necessary, or doxygen will ignore the file.
 * Do not use the star-exclamation form following the file statements,
 *   or what follows is not picked up as a brief description. 
 */


/*!
 * \brief (I live in test.h) Here is a one-liner function description.
 * \return (I live in test.h) Here is an explanation of the return value
 */

int main(int argc,    //!<[IN] more information about argc---shows only in the .h file
     char *argv[]     //!<[IN] a text vector---shows only in the .h file
);

和

//! \file test.c  a very lonely .C file 

#include <stdio.h>
#include "test.h"  /*!< non-functional comment */


// if you use any doxygen code in front of the function, then doxygen will
// warn that the return code of function main() is not documented, even
// though it is.  So, the below will warn.


/*! 
 * \internal (I live in .C.)  This is how I work wonders.
 */

int main(int argc, char *argv[]) {
  printf("I am working wonders!\n");
  return 0;
}

这样，函数名在 .h 文件中被原型化一次，在 .c 文件中被定义一次，两次都是在 C 中。（这是 C 语言的强制，不是 doxygen 的。）这样写时，doxygen足够聪明，可以自己拿起函数名，并理解原型和定义是相互的。不需要\fn。

也没有\param，需要重复参数名称，因为 doxygen 足够聪明，可以在原型定义后立即将其拾取。

.h 中的\return 仍然是必需的，因为我希望它在我的 .h 文件中，我可以在其中检查接口的含义。如果我能在 ');' 之后写 //![RETVAL] 会更好在 .h 原型中，但我找不到这样做的方法。再次，返回值没有命名，所以这没什么大不了的。

我还没有完全理解 \brief 和 \details 格式，但现在这已经不够冗余了。