律师事务所网站建设重要性,姜堰网站制作,网站服务商查询,男女插孔做暖暖的试看网站大全目录 1、什么是Doxygen?. 3 2、撰写正确格式的批注... 4 2.1常用指令介绍... 4 2.2简述与详述的方式... 6 2.3文件头注释... 6 2.4版权注释... 6 2.5模块定义#xff08;单独显示一页#xff09;... 7 2.6分组定义#xff08;在一页内分组显示#xff09;... 8 2.7变量、宏… 目录 1、什么是Doxygen?. 3 2、撰写正确格式的批注... 4 2.1常用指令介绍... 4 2.2简述与详述的方式... 6 2.3文件头注释... 6 2.4版权注释... 6 2.5模块定义单独显示一页... 7 2.6分组定义在一页内分组显示... 8 2.7变量、宏定义、类型定义简要说明... 8 2.8函数说明... 9 2.9枚举类型定义... 9 2.10项目符号标记... 10 3、使用DoxyWizard生成CHM文档... 11 1、什么是Doxygen? Doxygen是一个程序的文件产生工具可将程序中的特定批注转换成为说明文件。通常我们在写程序时或多或少都会写上批注但是对于其它人而言要直接探索程序里的批注与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式类别等等的说明。所以如果能依据程序本身的结构将批注经过处理重新整理成为一个纯粹的参考手册对于后面利用您的程序代码的人而言将会减少许多的负担。不过反过来说整理文件的工作对于您来说就是沉重的负担。 Doxygen就是在您写批注时稍微按照一些它所制订的规则。接着他就可以帮您产生出漂亮的文档了。 因此Doxygen的使用可分为两大部分。首先是特定格式的批注撰写第二便是利用Doxygen的工具来产生文档。 目前Doxygen可处理的程序语言包含 C/CJavaIDL (Corba, Microsoft及KDE-DCOP类型)   而可产生出来的文档格式有 HTMLXMLLaTeXRTFUnix Man Page 而其中还可衍生出不少其它格式。HTML可以打包成CHM格式而LaTeX可以透过一些工具产生出PS或是PDF文档。 2、撰写正确格式的批注 若需要通过Doxygen生成漂亮的文档一般有如下几个地方需要使用Doxygen支持的风格进行注释     1 文件头包括.h和.cpp         主要用于声明版权描述本文件实现的功能以及文件版本信息等     2 类的定义         主要用于描述该类的功能同时也可以包含使用方法或者注意事项的简要描述     3 类的成员变量定义         在类的成员变量上方对该成员变量进行简要地描述     4 类的成员函数定义         在类定义的成员函数上方对该成员函数功能进行简要描述     5 函数的实现在函数的实现代码处详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等 2.1常用指令介绍 可以在注释中加一些Doxygen支持的指令主要作用是控制输出文档的排版格式使用这些指令时需要在前面加上“\”或者“”JavaDoc风格符号告诉Doxygen这些是一些特殊的指令通过加入这些指令以及配备相应的文字可以生成更加丰富的文档下面对比较常用的指令做一下简单介绍。 file 档案的批注说明。 eg file    stm32f10x_tim.c author 作者的信息 eg author  MCD Application Team brief 用于class或function的批注中后面为class或function的简易说明。 eg brief   This file provides all the TIM firmware functions. param 主要用于函数说明中后面接参数的名字然后再接关于该参数的说明 eg param  TIMx: where x can be  1, 2, 3, 4, 5 or 8 to select the TIM peripheral. return 描述该函数的返回值情况 eg: return 本函数返回执行结果若成功则返回TRUE否则返回FLASE retval 描述返回值类型 主要用于函式说明中说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。 eg: retval NULL 空字符串。 retval !NULL 非空字符串。 note 注解 attention 注意 warning 警告信息 enum 引用了某个枚举Doxygen会在该枚举处产生一个链接 eg enum CTest::MyEnum var 引用了某个变量Doxygen会在该枚举处产生一个链接 eg var CTest::m_FileKey class 引用某个类 格式class name [header-file] [header-name] eg: class CTest inc/class.h exception 可能产生的异常描述 eg: exception 本函数执行可能会产生超出范围的异常 todo 对将要做的事情进行注释 see 一段包含其他部分引用的注释中间包含对其他代码项的名称自动产生对其的引用链接。 relates 通常用做把非成员函数的注释文档包含在类的说明文档中。 since 通常用来说明从什么版本、时间写此部分代码 deprecated pre 用来说明代码项的前提条件 post 用来说明代码项之后的使用条件。 code 在注释中开始说明一段代码直到endcode命令 endcode 注释中代码段的结束。 2.2简述与详述的方式 在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的但不能同时没有。 顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。 一般注释的描述由简述开始经过特殊分隔方式后后面紧跟详述的内容javaDoc风格可以使用的分隔方法有以下两种 1       使用brief 参数标识空行作为简述和详述的间隔标识 1.   /**   brief  Brief description.   2.    *    description continued.   3.    *   4.    *    Detailed description starts here.   5.    */  2 直接使用javaDoc风格javaDoc风格自动以简述开头以空行或者小数点加空格作为简述与详述的分割 1.   /**   Brief description   2.    *    description continued . (注意:这里有一个小数点,加上一个空格)   3.    *    Detailed description starts here.   4.    */  2.3文件头注释 2.4版权注释 1.   /** 2.     ****************************************************************************** 3.     * file    stm32f10x_dma.c 4.     * author  MCD Application Team 5.     * version V3.5.0 6.     * date    11-March-2011 7.     * brief   This file provides all the DMA firmware functions. 8.     ****************************************************************************** 9.     * attention 10.    * 11.    * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS 12.    * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE 13.    * TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY 14.    * DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING 15.    * FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE 16.    * CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS. 17.    * 18.    * h2centercopy; COPYRIGHT 2014  深圳电应普科技有限公司  /center/h2 19.    ****************************************************************************** 20.    */} 2.5模块定义单独显示一页  在文档注释块中使用defgroup命令来定义一个组。命令有两个参数第一个参数用来唯一标识组第二个参数是指明该组在文档中显示的标题。 1.   /**      2.    *    defgroup 模块名 模块的说明文字  3.    *     { 4.    */  5.     ... 定义的内容 ... 7.     8.   /** 9.    *      }// 模块结尾 10.   */ 如果你使用同一个组名一次以上那么你会遇到一个错误。你可以使用\addtogroup来代替\defgroup来防止doxygen只限制唯一的标识。它的用法和\defgroup是一样的不同的只是当多次使用一个组名的时候它会自动将其中的内容和之前的组名合并。组的题目在这里是可选的语法如下, 1.   /**      2.    *    addtogroup label  3.    *     { 4.    */  5.     ... 定义的内容 ... 7.     8.   /** 9.    *      } 10.   */ 2.6分组定义在一页内分组显示 1.   /**      2.    *    name 分组说明文字  3.    *     { 4.    */  5.     6.  ... 定义的内容 ... 7.     8.   /** 9.    *      }// 模块结尾 10.   */ 2.7变量、宏定义、类型定义简要说明 由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。 /*! 成员变量描述 */ 1在成员变量上面加注释的格式 1.   /** 成员变量描述 */  2.   int  m_Var;  2在成员变量后面加注释的格式 1.  int  m_color;     /*! 颜色变量 */      1.   /** brief 简要说明文字在前面加 brief 是标准格式 */ 2.  #define MIN_UINT 0    1.   /* 2.    *  分行的简要说明 \n 3.    *  这是第二行的简要说明 4.    */ 5.  int b;   2.8函数说明 1.   /* 2.    * 简要的函数说明文字 3.    *  param [in] param1 参数1说明 4.    *  param [out] param2 参数2说明 5.    *  return 返回值说明 6.    */ 7.   int func(int param1, int param2); 1.   /* 2.    * 打开文件 \n 3.    *  文件打开成功后必须使用 ::CloseFile 函数关闭。 4.    *  param[in] file_name 文件名字符串 5.    *  param[in] file_mode 文件打开模式字符串可以由以下几个模块组合而成 6.    *  - r 读取 7.    *  - w 可写 8.    *  - a 添加 9.    *  - t 文本模式(不能与 b 联用) 10.   *  - b 二进制模式(不能与 t 联用) 11.   *  return 返回文件编号 12.   *  - -1 表示打开文件失败 13.    14.   *  note 文件打开成功后必须使用 ::CloseFile 函数关闭 15.   *  par 示例: 16.   *  code 17.      // 用文本只读方式打开文件 18.      int f OpenFile(d:\\test.txt, rt); 19.   *  endcode 20.    21.   *  see ::ReadFile ::WriteFile ::CloseFile 22.   *  deprecated 由于特殊的原因这个函数可能会在将来的版本中取消。 23.   */ 24.  int OpenFile(const char* file_name, const char* file_mode);  2.9枚举类型定义 1.   /** 枚举常量 */ 2.   typedef enum TDayOfWeek 3.   { 4.     SUN 0, /*!  星期天注意要以 “” 小于号开头 */ 5.     MON 1, /*!  星期一 */ 6.     TUE 2, /*!  星期二 */ 7.     WED 3, /*!  星期三 */ 8.     THU 4, /*!  星期四 */ 9.     FRI 5, /*!  星期五 */ 10.    SAT 6  /*!  星期六 */ 11.  } 12.  /** 定义类型 TEnumDayOfWeek */ 13.  TDayOfWeek TEnumDayOfWeek; 2.10项目符号标记 通过在每行的开头添加一系列列对齐的减号(-)可以生成一个列表。列表项也可以具有标号这需要在减号的后面跟上一个#。列表也可以是嵌套的这取决于列表项的缩进方式。注意不要忘记-#后面的空格。 1.     /*! 2.      *  A list of events: 3.      *    - mouse events 4.      *         -# mouse move event 5.      *         -# mouse click event\n 6.      *            More info about the click event. 7.      *         -# mouse double click event 8.      *    - keyboard events 9.      *         1. key down event 10.     *         2. key up event 11.     * 12.     *  More text here. 13.     */  The result will be: A list of events: mouse events mouse move eventmouse click event More info about the click event.mouse double click event keyboard events key down eventkey up event 3、使用DoxyWizard生成CHM文档 安装好后开始菜单会多出doxygen菜单打开里面的DoxyWizard。界面如下图。 Step1是Doxygen的工作目录请指定一个已存在的非中文的文件夹。 Step2做具体配置工作。 首先是Wizard选项卡 Project Project name: 项目名称 Project version or id: 项目版本号 Source code directory: 项目源码目录 Destination directory: 文档输出目录 Mode 保持默认选项Document Entity Only与Optimize for C output即可。 Output 要生成CHM文档请选择HTML项中的prepare for compressed HTML (.chm)。 同时将With search function (requires PHP enabled web server)的钩去掉。 LaTeX如果不需要在文档中生成LaTeX公式的话可以不选。 Diagrams 选择第二项Use Build-In class diagram generator将使用Doxygen内置的生成功能生成每个类的类图如果它只有一个类的时候是不会生成的  。 如果需要使用更强大的功能比如类继承体系图请选择第三项Use dot tool from the GraphViz package此功能需要安装GraphViz软件。 其次是Export选项卡配置项比Wizard内容多出许多这里只做简单介绍。 Project OUTPUT_LANGUAGE选择Chinese。 TAB_SIZE 是Tab的长度默认为8大家根据自己喜好…… Build 默认是会生成public方法但是貌似有时会莫名奇妙地少掉一些方法的详细信息。 这里也选上EXTRACT_ALL它保证输出所有public方法及protected方法static方法不在此范围内。 若要包含static方法的注释请选中EXTRACT_STATIC。 同理EXTRACT_PRIVATE。 我们生成文档的目的是为了方便各位调用类与函数因此生成ALL、STATIC、LOCAL_CLASSES就好了吧  。 Messages 生成时的提示信息默认即可。 Input Input为输入目录支持多个目录我们可以放入项目目录和Include目录。 下面的Exclude是忽略目录与文件。 Source Browser 源码浏览器默认即可。 Index 钩选ALPHABETICAL_INDEX类中将有一个组合类型索引项。如下图所示 HTML 如果你之前选择了prepare for compressed HTML (.chm) 这里的GENERATE_HTMLHELP项会是钩选状态。 它下面的CHM_FILE填写你的CHM文档名字。 HHC_LOCATION则选择你的HTML Help WorkShop安装目录下的hhc程序 一般会在C:/Program Files/HTML Help Workshop/hhc.exe。 Doxygen生成的默认是UTF-8因此若不指定CHM_INDEX_ENCODING为GBK的话CHM会有部分乱码。 钩选TOC_EXPANDdoxygen会为你生成左边树目录。 Dot 如果你选用内置的生成功能即选择Use Build-In class diagram generator此时CLASS_DIAGRAMS会是钩选状态而HAVE_DOT则是未选状态默认即可; 如果你选用GraphViz的dot工具生成即选择Use dot tool from the GraphViz package情况则相反请你钩选上CLASS_DIAGRAMS。此时你需要设置下面的DOT_PATH为GraphViz的安装目录否则将无法生成。 另外以下选项钩选则生成对应的图不选则不生成 CLASS_GRAPHS                         类图COLLABORATION_GRAPH      协作图GROUP_GRAPHS                       组图UML_LOOK                                  是否UML外观INCLUDE_GRAPH                       includeINCLUDED_BY_GRAPH            被includeCALL_GRAPH                               调用CALLER_GRAPH                          被调用DIRECTORY_GRAPH                           目录图GRAPHICAL_HIERARCHY                  继承体系图 建议钩选以上下划线的几项。效果应如下所示 DOT_IMAGE_FORMAT是生成的图片类型有PNG/JPG/GIF三种格式可选。 其他项没有用过请大家自己研究  。 配置好后即可运行进入Run选项卡单击Run doxygen即开始生成。 对话框会显示调试信息生成好后点击下面的Show HTML Output可以打开生成的HTML首页。 chm文件则在你指定的生成目录中自己找。 关闭前不要忘了保存配置文件下次可以继续使用。 它会自动提示你是否需要保存你也可以选择File菜单的Save项自己保存。