大家在平时的编程过程中,都会在代码中插入一些注释,对文件,类,函数,全局变量等进行简单说明.项目完成后,一般也要编写项目的文档,如何利用源代码及其中的注释,自动生成图文并茂的文档,就是下面要介绍的. 1 工具 文档自动生成的工具软件,除了商业化的如Rational SoDA等,更有开源的Doc++和Doxygen等. 本文主要介绍功能全面的Doxygen. Doxygen可以对C++, C, Java, Python等语言进行解析并生成HTML,LaTeX,RTF,man page,XML等格式的文档. 除了必备的Doxygen (http://www.stack.nl/~dimitri/doxygen/), 如果你还想生成漂亮的类图等,还需要下载graphviz (Doxygen 采用的绘图工具,http://www.graphviz.org/Download..php). 2 Doxygen 的注释格式 Doxygen 的注释格式十分灵活.可以是JavaDoc, Qt和仿c++风格, 并且可以混合使用. 如果你熟悉Doc++,就按照你以前的风格写好了:). 下面对每种风格简单举例: -- JavaDoc风格: /** * your comment text. */ -- Qt风格: /*! * your comment text. */ -- 仿c++风格: /// //! /// your comment text. 或者: //! your comment text. /// //! 因为我一直喜欢用c++的单行注释风格(即'//'),所以下面举例就以仿c++风格为例. 下面注释中的'@'和'\'等价,可以根据爱好选用. 因为是在头文件中定义接口,所以注释也就主要集中于头文件中. 如果你想在实现文件中注释,其效果和在头文件中是一样的.下面就举一个实例. 备注:a) '#' 后面的注释是我加的简单解释.不属于文档注释内容. b) Doxygen 允许一条简短注释,加上一条详细注释.其格式也是多样的. 一般,在 JAVADOC_AUTOBRIEF = NO时,简短注释(///@brief )后空一行,然后再是详细注释. 当 JAVADOC_AUTOBRIEF = YES时,并且简短注释以第一个句号结束,句号后跟一空格(即'. ');或者是新起一行,就可以写详细注释了.示例如下: # 简短注释. 详细注释. /// Brief description which ends at this dot. Details follow /// here. c) 如果同一代码条目在声明和定义处都有简短注释和详细注释, 则文档只采用声明前的简短注释和定义前的详细注释. d) 如果是在行尾注释变量,参数等,在你选用的注释格式后面加上'<', 如: ///<行尾的注释. ----------------------------- Example Begin --------------------------------- # 文件的注释格式 # 注释文件,格式: ///@file 文件名 文件的简短注释. ///@file socket_c.h head file of class socket_c. # 文件的详细注释. ///Define the interface of class socket_c. # 普通注释,不会生成在文档中. //$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $ # 类的注释,格式: ///@brief 简短注释内容. ///@brief class of server socket. class socket_c { private: public: # 函数的注释格式 # 函数的注释,格式: ///@brief 函数的简短注释. ///@brief handle the connections of clients. # 参数注释,格式: ///@param 参数的简短注释. ///@param server the server ip address. ///@param serv_port the server #port. # 返回值注释,格式: ///@return 返回值的简短注释. ///@return connected socketfd. # 具体返回值的注释,格式: ///@retval 返回值 该返回值的注释. ///@retval connfd on success. ///@retval 0 on EINTR - system call. ///@retval -1 on error. # 参见...,格式: ///@see 参见的类/文件等. ///@see main_ppc.cpp int accept_client(const int listenfd); }; # 自定义类型的注释 ///@brief structure of child process. struct child_proc_s { # 行尾的注释,格式: ///< 注释内容. pid_t child_pid; ///<child process id. int child_pipefd; ///<parent's stream pipe to/from child. }; # 全局变量的注释,也可以采用上面的行尾格式进行注释. ///gloable variable for signal. pid_t g_pid = 0; ----------------------------- Example End --------------------------------- 3 配置文件的生成与修改 Doxygen的功能强大,配置选项也十分多. 如果是命令行模式, 有些不便. 因此建议使用GUI的Doxywizard(可以从<开始>菜单中运行). 下面就对我个人认为比较重要的选项,并结合实例 (生成html文档) 进行简单说明. 下面列出的一般是需要修改的,未列出的我采用缺省值. # Project选项 #--------------------------------------------------------------------------- # Staff_TPC是生成文档的项目名,会显示在文档中. PROJECT_NAME = Staff_TPC PROJECT_NUMBER = 1.0 # 项目版本号 # 生成文档的输出路径 OUTPUT_DIRECTORY = "f:/My Documents/cpp/horin/staff/" # 生成文档的语言,缺省是English,也可以是简体中文等. OUTPUT_LANGUAGE = English JAVADOC_AUTOBRIEF = YES # 打开此选项. # Build 选项 #--------------------------------------------------------------------------- SHOW_INCLUDE_FILES = NO # 不显示所有包括的文件. # input 选项 #--------------------------------------------------------------------------- # 要生成文档的源文件的路径. 如果是一个目录,则是该目录下的所有文件; 当然,也可以 # 是具体的某个文件. INPUT = "f:/My Documents/cpp/horin/staff/tpc/" # 输入文件的匹配模式,下面是c / c++语言的设置. FILE_PATTERNS = *.c \ *.cpp \ *.h \ *.hpp RECURSIVE = YES # 需要递归处理子目录. # source browser选项 #--------------------------------------------------------------------------- # 如为SOURCE_BROWSER和INLINE_SOURCES都设置为YES, 则生成的文档中会包括源代码 # (即.cpp文件),这可以方便阅读时查看源代码. SOURCE_BROWSER = NO INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES # 忽略普通的文档注释. REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES VERBATIM_HEADERS = YES # HTML 选项 #--------------------------------------------------------------------------- GENERATE_HTML = YES # 需要生成html格式的文档. GENERATE_HTMLHELP = YES # 需要生成windows HTMLHELP格式的目录,以方便阅读. GENERATE_TREEVIEW = YES # 需要生成树视图,以方便阅读. # LaTeX 选项 #--------------------------------------------------------------------------- GENERATE_LATEX = NO # 不需要生成LaTeX输出. # dot 选项 # 此选项是生成图形,建议(需要)安装graphviz. #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES # 已经安装graphviz.打开此选项. CLASS_GRAPH = YES # 生成类图 COLLABORATION_GRAPH = YES # 生成协作图 UML_LOOK = NO 在上面根据自己的需要对各个选项进行了配置,下面很重要的一步,就是把配置保存下来. 呵呵,这是大家最擅长的了. 可以命名配置文件为Doxygen-YourName.txt, 今后只需修改project和input选项,即可重用. 4 文档的生成 在Doxywizard中打开上面的配置文件Doxygen-YourName.txt, 根据需要修改project和input选项(也可以在文本编辑器中直接修改Doxygen-YourName.txt), 点击菜单Doxygen->Run(ctrl+r),稍微休息一会,你就可以看到在OUTPUT_DIRECTORY路径下生成了一个html的子目录.该子目录下就是你需要的文档. 运行index.html文件, 是否见到了你想要的.很有可能,还见到了你意想不到的. 5 Doxygen的其他用途 Doxygen配合graphviz, 可以生成UML设计图形,如类图,协作图. 如你拿到一份源代码,因为类的关系复杂,或者没有文档, 此时你就可以利用Doxygen来进行简单的反向工程了. |
联系客服
