doxygen --文档自动生成工具

      为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释， 注释如何写，写多少等这些问题，很多程序员仍然没有答案。更头痛的是写文档，以及维护文档的问题，开发人员通常可以忍受编写或者改动代码时编写或者修改对 应的注释，但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档，对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动 转化为对应的文档。

 

       Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。或者生成包含依赖图、继承图以及协作图来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。

      可以生成CHM格式的文档系统，比较适合制作API的接口文档.可以生成html格式的文档系统，从而放到公司内网，便于代码和文档保持同步.对文档做版本管理.维护用 C/C++ 开发的遗留系统并添加新特性是一项艰难的任务。这涉及几方面的问题：理解现有的类层次结构和全局变量，不同的用户定义类型，以及函数调用图分析等等。  此工具可以帮助完成这个任务。

 

     风格一：
    //! sample

    风格二：
    /*!
    sample
    */

 

    需要的软件：

     a、doxygen: 自动生成文档工具
     b、graphviz: doxygen需使用该软件的画图功能
     c、HTML Help Workshop: 编译生成chm的工具

 

     上述3个软件安装完成后，直接使用doxygen就可以生成html格式(gb2312)。如果需要生成chm格式，则用HTML Help Workshop打开html目录下的index.hhp编译即可

 

      常用指令：

 @file
档案的批注说明。
@author
作者的信息
@brief
用于class 或function的简易说明
eg：
@brief 本函数负责打印错误信息串
@param
主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return
描述该函数的返回值情况
eg:
@return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval
描述返回值类型
eg:
@retval NULL 空字符串。@retval !NULL 非空字符串。
@note
注解
@attention
注意
@warning
警告信息

          基本结构的说明标记：

   /file [file name]   写文件的说明， 后跟此文件的文件名；另起一行书写此文件的说明文字。
   /class [class name] 写类的说明，后跟类名；另起一行书写类的说明文字。
  
用于函数内部的说明标记：
   这些标记会在函数的详细说明中使用不同的字体和格式，突出显示。
   /param [param name]   写函数参数的说明，后跟参数名；紧跟参数的说明文字。
   /return      写函数返回值得说明，后紧跟返回值得说明。
   /warning     警告，后紧跟警告的内容。
   /remarks     评论，后紧跟评论的内容。
  
可单独生成主题的说明标记：
   /todo      被此标记说明的代码会在 Todo 列表中出现。
   /bug      被此标记说明的代码会在 Bug 列表中出现。
   /test      被此标记说明的代码会在 Test 列表中出现。
   /deprecated     被此标记说明的代码会在 deprecated 列表中出现。
   /defgroup [group name] [brief] 定义一个代码块，可对代码块写说明 ; 注意 group name 必须是唯一的；
          另起一行写详细说明
    /{ 代码块开始
    /} 代码块技术
  
格式化说明标记：
   - 主题
    -# 子标题 1
     说明
    -# 子标题 2
     说明                     生成文档中可显示为编号的列表   注意：在注释中，可完全使用 html 格式化标记。

 

     注意：

   注释中的换行需要该行末加入 /n
注释中的换行也可以多余一个空行来实现
编码格式使用gb2312
如果想让html页不忽略空格和换行，则可以用preformat 如下
/*!<pre>
</pre>*/
需要生成文档的注释只能写在头文件中

 

QA:

2010/8/19 Dimitri van Heesch <dimitri@stack.nl >

On Aug 18, 2010, at 10:11 , wrote:

> hello,
>
>      when  i use doxygen1.7.1, i find that when i write 2 lines in the detail comment,  the generated htmls do not show 2 line in the page.
> but i do not want to use the "/n" or other something, please tell me how can i achieve this goal?  could it do by configuring something or
>  some other commands?
>
>
> for example
> /*!
> i am ok
> you are ok
> */

You can use this to get preformatted text:

/*!
<pre>

i am ok
you are ok

</pre>
*/

You could even write an input filter (see INPUT_FILTER in the config file) that
replaces "/*!" by "/*! <pre>" and the corresponding "*/" by "</pre> */" on the fly, so you
get this behaviour automatically.

Regards,
 Dimitri