【原创】利用doxygen来管理项目文档或注释，doxygen项目一、doxygen应用场景：doxygen可以用来管理目前主流的编程语言的注释而形成文档系统。（包括c, c++, c#, objective-c, idl, java, vhdl, php, python, tcl, fortran等）。doxygen官网地址（http://www.doxygen.nl/）近来大部分时间花在api接口的维护上面，其中比较重要的一个环节就是你写的接口如何让调用者一目了然的理解用法。不管是内部无线服务端与客户端之间的配合，还是对外开放的api接口，都一样。花了几天时间尝试了下使用doxygen结合svn hook来管理接口文档还是很方便实用的。doxygen官网自己本身其实就是利用doxygen来做的，如果大家想要看更具体的效果，就可以直接参考http://www.doxygen.nl/。以下先贴出我自己做出来的部分效果图，ui很挫，大家真正使用时可以让公司ui部门美化下，由于我目前还主要是内网使用，因此没有去过多考虑ui体验：
二、安装：doxygen目前已经比较全面的支持了windows、mac ox、linux等主流系统。而且基本上使用于目前所有的主流编程语言。这里简要介绍下自己在ubuntu系统下面的源码编译安装过程。其余安装方法可以参考官网。三、使用doxygen之配置文件的配置：doxygen的使用可以说就是对配置文件的配置，就是说，你只要稍微配置一下配置文件，再执行一下命令： xxxx/doxygen  xxxx.conf  就可以生成你想要的文档（这里doxygen提供了多种格式的文档，我主要用的是html的，这样我们可以自己配置一个web服务到这个html上面，就可以再web上面使用文档了。），doxygen提供了200多个配置项，通过配置文件就已经可以完成丰富的功能了，下面举一些常用的配置说明：
利用命令xxx/doxygen -g 就会在当前目录下面产生一个默认配置文件 doxygen.conf。打开默认配置文件，你会发现里面每一个配置项都是 配置名   配置值 这样的key-value格式，如果你有一定的英文功底的话，配置基本上就不是什么问题了。配置的详细说明请参考：http://www.stack.nl/~dimitri/doxygen/manual/config.htmlabbreviate_brief                //简短摘要aliases                                //别名allexternals                      //所有外部文档alphabetical_index              //字母顺序索引always_detailed_sec            //详细描述部分binary_toc                        //二进制操作brief_member_desc              //简短的成员描述call_graph                       //调用到的图case_sense_names              //检测的范例的名字chm_file                          //chm格式文件class_diagrams                 //类-表class_graph                         //类-图dot_path                            //dot路径设置dot_transparent                //dot转换设置dotfile_dirs                      //dotfile 列表显示enable_preprocessing      //允许预处理指令enum_values_per_line      //每行的枚举值enabled_sections           //允许分段显示example_path                     //例子路径example_patterns            //例子用的文件格式（*.cpp, *.h , *.java等）example_recursive             //例子递归collaboration_graph          //相互调用关系图cols_in_alpha_index           //以列形式显示的字母顺序的索引compact_latex                  //压缩的latex文档compact_rtf                    //压缩的rtf文档create_subdirs                //创建一个子目录details_at_top                 //文档的详细头部directory_graph                  //目录图disable_index                      //禁用indexdistribute_group_doc       //禁用文档成组显示dot_image_format            //点阵图形dot_multi_targets           //多个dot目标exclude                             //可执行文件exclude_patterns           //可执行文件格式（*.exe, *.dll等）exclude_symlinks              //可执行的symlinksexpand_as_defined             //规定的扩展expand_only_predef        //预定义扩展external_groups              //使用到的外部的文件extra_packages                //使用到的外部插件包extract_all                      //提取所有extract_local_classes      //提取所有本地类extract_local_methods   //提取所有本地方法extract_private                 //提取所有privateextract_static                  //提取所有staticfile_patterns                     //文件路径file_version_filter            //文件版本控制filter_patterns                  //控制格式（主版本：第1次版本：第2次版本号）filter_source_files           //原文件的版本控制full_path_names               //全路径名generate_autogen_def      //生成自动定义文件形式generate_buglist              //生成bug列表generate_chi                     //生成希腊字母generate_depreciatedlist //生成评估列表generate_html             //生成htmlgenerate_htmlhelp            //生成htmlhelpgenerate_latex                 //生成latexgenerate_legend                //生成图例generate_man                    //生成man文件generate_perlmod        //生成perl脚本generate_rtf                     //生成rtfgenerate_tagfile               //生成标志文件generate_testlist       //生成testlistgenerate_todolist            //生成todolistgenerate_treeview          //生成树状视图显示generate_xml                    //生成xmlgraphical_hierarchy          //继承图表group_graphs                    //组-图have_dot                          //隐藏dothhc_location                    //隐藏位置hide_friend_compounds  //隐藏复合的友员类型hide_in_body_docs            //隐藏文档的主体hide_scope_names        //隐藏作用域名hide_undoc_classes          //隐藏未归档的所有classhide_undoc_members         //隐藏未归档的所有的成员hide_undoc_relations //隐藏未归档的关系html_align_members          //html文档中成员对齐方式html_footer                     //html脚注设置html_header                      //html头部设置html_output                     //html输出设置html_stylesheet               //html样式设置ignore_prefix                    //忽略哪些前缀image_path                  //图片的路径设置include_graph              //包含-图include_path                     //头文件包含的路径inherit_docs                     //文档的继承关系inline_info                  //内联信inline_inherited_memb   //通过继承得到的内联成员inline_sources                  //内联部分的源代码input                                 //输入设置input_filter                      //能够接受的输入文件的扩展名格式设置（重要）internal_docs             //内部文档javadoc_autobrief            //javadoc工具生成的文档的自动摘要latex_batchmode               //latex匹配方式latex_cmd_name                //latex 命令名latex_header                     //latex 头部latex_hide_indices            //latex内部隐藏的包含latex_output                    //latex输出macro_expansion              //宏展开设置（重要）makeindex_cmd_name         //makeindex命令索引man_extension                  //man扩展man_links                          //man 链接设置man_output                      //man输出设置max_dot_graph_depth //dot图的最大深度max_dot_graph_height      //dot图的最大高度max_dot_graph_width       //dot图的最大宽度max_initializer_lines   //最大初始化行multiline_cpp_is_brief       //多 个cpp文件的简短描述multiline_cpp_is_brief       //多 个cpp文件的简短描述optimize_output_for_c     //对c采用的优化设置optimize_output_java //对java采用的优化设置output_directory        //输出路径设置（重要）output_language              //输出语言设置（重要）paper_type                        //纸张类型pdf_hyperlinks                  //pdf格式超链接设置（重要）perl_path                          //perl路径设置perlmod_latex             //perlmod latexperlmod_pretty                 // perlmod pretty（漂亮/相当）perlmod_makevar_prefix  //perlmod make文件版本 prefixpredefined                    //预先定义（重要）project_name                     //工程名（重要）project_number                  //工程的组成成员（重要）quiet                                 //静态量设置（重要）recursive                           //递归和循环referenced_by_relation   //交叉参考（重要）references_relation           //交叉参考的关系repeat_brief                       //重新设置简短说明为打开状态rtf_extensions_file           //rtf展开文件rtf_hyperlinks                   //rtf超链接rtf_output                        //rtf输出设置rtf_stylesheet_file           //rtf样式文件search_includes                 //搜索时需要包含什么（重要）searchengine                      //搜索引擎设定（重要）short_names                      //使短文件名生效show_directories         //显示目录show_include_files            //显示包含文件（一般no，否则太大）show_used_files                //显示被用到的文件（一般yes）skip_function_macros        //跳过函数中的宏（重要），菜鸟最好别跳sort_brief_docs                //文档的简短摘要sort_member_docs             //成员的简短描述source_browser                 //原文件浏览路径strip_code_comments  //排除哪些条码形式注释（重要）strip_from_inc_path          //排除哪些头文件包含的注释（重要）strip_from_path                //排除哪些条码路径设置subgrouping                       //子组设置（重要）tab_size                             //tab符size设置（重要）tagfiles                             //标志文件template_relations            //模板关系设置（重要）toc_expand                        //toc扩展treeview_width                 //树状图显示的宽度设置（重要）uml_look                            //uml外观设置（重要）use_windows_encoding   //使用windows系统的编码形式（重要）verbatim_headers         //verbatim头部（头文件）warn_format                     //警告格式指定（重要）warn_if_doc_error            //如果文档出错则显示警告warn_if_undocumented   //如果是未归档文件则显示警告warn_logfile                     //警告日志文件设置warn_no_paramdoc            //无参数文档警告形式设定warnings                           //警告设置（重要）xml_dtd                             //xml文件类型定义（重要）xml_output                        //xml输出设置（重要）xml_programlisting           //xml程序列表（重要）xml_schema                        //xml模式设置（重要）
四、doxygen配置完成后注释的书写当你配置好doxygen后，今后你基本上的时间都是花在你代码当中的注释的书写和维护。想要利用doxygen来管理文档。那么代码的注释就不需严格要求。/** * @brief 这里用brief来说明接口方法的主要功能 * @date 接口方法的创建时间 * @author 接口方法的创建人 * @param : 参数说明如下表： * name | type |description of param * ----------|-----------|-------------------- * car_id | int |车源编号 * province | int |业务员所在省份 * x | x | x * x | x | x * x | x | x * @return 返回值说明如下： * name | type | description of value * -------- |----------|---------------------- * car_id | int | 车源编号 * car_info | object | json对象格式的车源信息 * @warning 该接口需要告知给调用者看的一些警告 * @attention 该接口需要告知给调用者看的一些注意事项 * @note 该接口的一些备注说明。通常用于当后者对该接口有较大改动的时候。备注一下某个时间点某人改动了什么东西 * @ todo 该接口的一些未完成的待办内容 */public function newsale() { do someting; }
按照规范书写注释后，在页面文档中展示的效果如下：
在项目内部可以提前约定好书写规则，余下的只要大家按照这个规则来维护即可。当然人毕竟是人，不可能保证所有的代码都能按照预期的注释规则书写。因此doxygen的配置文件里面可以指定日志文件的路径。你可以好好利用这个日子文件，用相应的脚本语言写一小段代码来分析这个日志文件，然后人性化点展示到web页面上面。指定的管理人员定期的去查看下注释错误日志，即可即时纠正不对的注释内容。
五、doxygen的比较常用的特性doxygen的功能还远远不止我上面介绍的那些，还有很多丰富多彩的功能，有想要使用这东西的人，可以自己去doxygen官网上面学习下哈。本文可随意转载，但是请务必注明原文出处。
http://www.bkjia.com/phpjc/922301.htmlwww.bkjia.comtruehttp://www.bkjia.com/phpjc/922301.htmltecharticle【原创】利用doxygen来管理项目文档或注释，doxygen项目 一、doxygen应用场景： doxygen可以用来管理目前主流的编程语言的注释而形成文档系统...