Chinaunix首页 | 论坛 | 博客
  • 博客访问: 861380
  • 博文数量: 156
  • 博客积分: 6553
  • 博客等级: 准将
  • 技术积分: 3965
  • 用 户 组: 普通用户
  • 注册时间: 2010-06-22 18:36
文章存档

2012年(3)

2011年(43)

2010年(110)

分类: 项目管理

2011-10-10 18:30:17

要使用doxygen来生成帮助文档,需要修改源代码文件,规范现有注释。为了使注释轻松智能的变成可读的文档。doxygen规定了自己的注释格式,这样太才可以解析。最常用的注释格式是:

/**
  there is comment.
*/


/*!
  there is comment.
*/

同时,为了区分注释的用途,doxygen定义了很多关键字,用来标识注释描述的代码段或者用途。常用@后面跟用途关键字来标识,关键字在doxygen附带的帮助文件中有很详细的解析(Special Commands这一节中),这里就不在累赘了。这里有一个地方需要注意一下,描述的各个分段之间最好用tab空开,用空格有的时候会出现问题。
如:

/**
  * @brief
这是一个函数
  * @param a
参数一
  * @param b
参数二
  * @return
无返回值
  */
  void fooFun(int a, int b);

我在这里主要讲一些基本常用的属性,很多我觉得意义不大的,请自行研究,这里就不过多解释了。
      
[Wizard...]中没有特别复杂的地方,稍微看一眼便知。

       [Expert...]按钮中,有一个tab页,下面来逐一解释:

         Project页面,主要包括项目的基本配置。
             TAB_SIZE
主要是帮助文件中代码的缩进尺寸,譬如@code@endcode段中代码的排版,建议符合习惯,设置成4
             OPTIMIZE_OUTPUT_FOR_C
这个选项选择后,生成文档的一些描述性名称会发生变化,主要是符合C习惯。如果是纯C代码,建议选择。
             SUBGROUPING
这个选项选择后,输出将会按类型分组。
               
         Build
页面,这个页面是生成帮助信息中比较关键的配置页面
             EXTRACT_ALL
表示输出所有的函数,但是privatestatic函数不属于其管制。
             EXTRACT_PRIVATE
表示输出private函数。
             EXTRACT_STATIC
表示输出static函数。同时还有几个EXTRACT,相应查看文档即可。
             HIDE_UNDOC_MEMBERS
表示那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然,如果EXTRACT_ALL被启用,那么这个标志其实是被忽略的。
             INTERNAL_DOCS
主要指是否输出注解中的@internal部分。如果没有被启动,那么注解中所有的@internal部分都将在目标帮助中不可见。
             CASE_SENSE_NAMES
是否关注大小写名称,注意,如果开启了,那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说,建议永远不要开启。
             HIDE_SCOPE_NAMES
域隐藏,建议永远不要开启。
             SHOW_INCLUDE_FILES
是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列表。
             INLINE_INFO
如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。
             SORT_MEMBER_DOCS
如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显示。
             GENERATE_TODOLIST
是否生成TODOLIST页面,如果开启,那么包含在@todo注解中的内容将会单独生成并显示在一个页面中,其他的GENERATE选项同。
             SHOW_USED_FILES
是否在函数或类等的帮助中,最下面显示函数或类的来源文件。
             SHOW_FILES
是否显示文件列表页面,如果开启,那么帮助中会存在一个一个文件列表索引页面。

         Messages页面主要用来设置编译时的输出信息选项。编译时的输出信息,主要可以用来提醒一些输入的错误语法。
             QUIET
如果开启,那么表示关闭编译时的输出信息。
             WARN_FORMAT
表示日志输出的格式,没必要修改。
             WARN_LOGFILE
表示信息是否输出到LOG文件,因为有DoxyWizard的存在,所以这个选项没有必要使用。


         HTML
页面
             CHM_FILE 表示输出的chm文件路径
             GENERATE_CHI
表示索引文件是否单独输出,建议关闭。否则每次生成两个文件,比较麻烦。             
             TOC_EXPAND
表示是否在索引中列举成员名称以及分组(譬如函数,枚举)名称。
             
这个页面关系到生成chm的问题,不过很多选项很简单,一看便知。

 

         Preprocessor 页面是预处理页面,里面也有一些配置,但是个人感觉使用默认就行了。其他的几个页面,基本上都要依赖于某些其他第三方的模块,尽管有些doxygen自带了,但是其详细说明,还得考读者自行研究。

 

 

         同时附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen自建命令,HTML命令方式和XML命令方式。所有的命令都是以'\'或者字符开头,这表明如果你的注释中有'\'开头的单词,你必须要修改成'\\'

         由于doxygen命令比较多,另外就是doxygen的帮助文档也是非常完善,所以,这里仅仅列举几个常用的命令,其他命令请自行参考帮助文件。

@addtogroup 添加到一个组。
@brief  
概要信息
@deprecated 
已废弃函数
@details  
详细描述
@note  
开始一个段落,用来描述一些注意事项
@par  
开始一个段落,段落名称描述由你自己指定
@param  
标记一个参数的意义
@code .. @endcode 
包含一段代码
@fn  
函数说明
@ingroup 
加入到一个组
@return  
描述返回意义
@retval  
描述返回值意义
@include 
包含文件

如何像MSDN那样在左边的树中显示函数列表?
      
打开[Expert...]HTML页面,然后选中TOC_EXPAND即可。

阅读(7467) | 评论(0) | 转发(1) |
给主人留下些什么吧!~~