C 请推荐doxygen快捷方式

我必须用C写一些代码，所以我决定学习doxygen和subversion

我希望我的文档简洁明了，没有任何冗余。这很有帮助，但还不够。我需要反冗余建议

某处是否有含等效物的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手册建议全局变量有时需要它。/*！<在structs*/中的变量之后使用，我想这是一个较长的缩写，但我不确定。是否需要\详细信息，或者在\简要信息之后的较长注释是否假定为详细信息？一些帖子说文件名由版本控制系统保存，但我的subversion手册没有提到doxygen，我的doxygen手册也没有提到subversion。

因此，以下是我为减少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
);

及

这样，函数名在.h文件中原型化一次，在.c文件中定义一次，两次都是在c中。这是一种c语言强加，而不是doxygen的。当以这种方式编写时，doxygen足够聪明，可以自己选择函数名，并理解原型和定义是相互关联的。不需要\fn

也不需要参数名为repeation的\param，因为doxygen足够聪明，可以在原型定义之后立即获取它

\return in.h仍然是必需的，因为我希望它在我的.h文件中，在那里我可以检查接口的含义。如果我能写，那就更好了！[RETVAL]在“；”之后在.h原型中，但我找不到这样做的方法。同样，返回值没有命名，所以这没什么大不了的

---

我还没有完全了解\short和\details的格式，但现在已经足够了。

我想/*！<…*/只是意味着文档注释适用于上一个声明，而不是下一个声明。在结构定义中经常使用它，只是因为如果文档可以放在同一行中，那么在以后使用文档在美学上会更好，但是我非常确定/*！…*/可以在结构成员之前使用，其工作原理相同。如果使用/*！…*/之前，我们如何将其与结构的各个部分相匹配？我想知道/*！<…*/也可以更好地用于避免使用\param？！你试过Mecurial而不是SVN吗？@ivoWelch:在整个结构之前你不会使用它；在结构的每个成员之前使用它，例如struct person{/*！…*/const char*name；/*！…*/unsigned int age；}；在使用//时，doxygen有时似乎很挑剔，有时却不挑剔！vs/*！表格*/s。我不知道我是否不了解这个系统，或者这些是准错误。

//! \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;
}