Question

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

我希望我的文档简明扼要，不合理。 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; }

有很多冗余需要保持检查修订。我发现了一些快捷方式，但这是随机的。上述帖子中的一些人声称不需要\文件，doxygen手册表明它有时需要全局变量。 / *＆LT！;在结构中的变量之后使用* /这是一个不那么冗余的缩写，我推测（但我不确定）。是\必须提供详细信息，还是在\ brief被认为是详细信息之后的更长时间的评论？一些帖子声称文件名是由版本控制系统保存的，但是我的subversion手册没有提到doxygen，而我的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＆＃39;）。这样，doxygen足够聪明，可以自己获取函数名，并了解原型和定义是否属于彼此。不需要\fn。

还没有\param，必须使用参数名称重复，因为doxygen非常聪明，可以在原型定义之后立即进行拾取。

.h中的\return仍然是必要的，因为我想在我的.h文件中，我可以检查界面的含义。如果我能在＆＃39;之后写出//！[RETVAL]，那就更好了。＆＃39;在.h原型中，我找不到办法做到这一点。再次，返回值没有命名，所以这没什么大不了的。

我尚未完全了解\brief和\details格式，但现在这已经不够冗余了。

请推荐doxygen快捷方式

1 个答案: