Doxygen

曾经听过这样一个段子

作为一个coder，最烦两件事：
一个写文档，另一个则是看代码时没文档。

笑话归笑话，但却真实的反应了一个尴尬的现状：文档对于一个软件项目非常重要，但维护高质量的文档又会增加许多非coding的工作量。
这一章就来介绍一个coder的好朋友：doxygen。它可以解析出源码文件中的注释信息，并输出精美的文档供阅读代码的人查阅。

安装doxygen

# git clone https://github.com/doxygen/doxygen.git  
# cd doxygen
# cmake -G "Unix Makefiles" .
# make
# make install
# doxygen -h   // 验证安装是否成功

使用doxygen

# doxygen -g        // 生成配置文件Doxyfile
# vim Doxyfile      // 编辑配置文件，注释写的非常详细。一般改一下OUTPUT、INPUT相关的就可以了  
# doxygen Doxyfile  // 根据配置，生成文档

代码注释

要用doxygen解析源码中的注释来生成文档，自然注释的格式就需要一定的定制才行。doxygen支持的注释格式比较多，下面仅介绍个人比较偏爱的格式。其他格式可自行参阅官方manual。

• 代码块注释方法

  /**
  * Comments for code block
  */
  

• 简要注释: 使用brief关键字

  /**
  * \brief This would be a brief explanation.
  *
  * Here is a more detailed explanation.\n
  * An empty line need to be added after brief explanation.
  */
  

• 变量注释方法: 相比于块注释，多了一个'<'

  int var; /**< Detailed description after the member */
  

• 函数注释

  /**
  * a normal member taking two arguments and returning an integer value.
  * @param a an integer argument.
  * @param s a constant character pointer.
  * @see Javadoc_Test()
  * @see ~Javadoc_Test()
  * @see testMeToo()
  * @see publicVar()
  * @return The test results
  */
  int testMe(int a,const char *s);
  

  上面这段代码生成的HTML文档大概如下：
  

To document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a
/*! \file */
or a
/** @file */
line in this file.

参考资料

Doxygen Manual