使用CodeBlocks和插件Doxygen(doxyblocks)定义代码模板并生成帮助文件

Love The Way You Lie 2021-12-10 23:53 579阅读 0赞

### 文章目录 ###

*  配置项目模板文件
 *   *  CodeBlocks变量扩展(可用的内置命令)
     *  利用Doxyblocks(doxygen)导出生成项目说明文档时出错
     *  利用Doxyblocks(doxygen)自动生成文件和函数注解
     *   *  自动生成文件注解
         *  自动生成函数注解
 *  参考文章：

# 配置项目模板文件 #

1.项目模板 在Documents and Settings< user >\\Application Data\\ codeblocks\\UserTemplates目录中.

2.配置默认代码

设置->编辑器->默认代码，编写时参考以下:

## CodeBlocks变量扩展(可用的内置命令) ##

**时间和日期**

*  $(TDAY) Current date in the form YYYYMMDD (for example 20051228)
 *  $(TODAY) Current date in the form YYYY-MM-DD (for example 2005-12-28)
 *  $(NOW) Timestamp in the form [YYYY-MM-DD-hh.mm][] (for example 2005-12-28-07.15)
 *  $(NOW\_L) Timestamp in the form YYYY-MM-DD-hh.mm.ss (for example 2005-12-28-07.15.45)
 *  $(WEEKDAY) Plain language day of the week (for example ’Wednesday’)
 *  $(TDAY\_UTC), $(TODAY\_UTC), $(NOW\_UTC), $(NOW\_L\_UTC), $(WEEKDAY\_UTC) These are identical to the preceding types, but are expressed relative to UTC.
 *  $(DAYCOUNT) The number of the days passed since an arbitrarily chosen day zero (January 1, 2009). Useful as last component of a version/build number.

**语法**

Code::Block对待下面的功能相同的字符序列 内部预编译，生成后的，或构建的步骤和变量：

$变量

$(变量)

$\{变量\}

%变量%

变量名必须包含字母数字字符,不区分大小写。 变量从一个散列号( \# )被解释为 全局编译器变量 。 下面列出的名称解释为内置类型。

变量是全局用户变量和内装式类型替换值提供的项目文件,或一个环境变量如果后者应该失败。

Per-target定义优先于per-project的定义。

内置的变量扩展就像预定义宏扩展在C预处理器处理时它将文本替换。

**可用的内置命令列表**

**CodeBlocks workspace**

*  (WORKSPACE\_FILENAME), $(WORKSPACE\_FILE\_NAME), $(WORKSPACEFILE), $(WORKSPACEFILENAME) 当前工作空间项目的文件名(.workspace)。
 *  $(WORKSPACENAME), $(WORKSPACE\_NAME)  显示在选项卡项目的管理面板的工作空间的名称
 *  $(WORKSPACE\_DIR), $(WORKSPACE\_DIRECTORY), $(WORKSPACEDIR), $(WORKSPACEDIRECTORY)  工作空间目录的位置.

**文件和目录**

*  $(PROJECT\_FILENAME) , $(PROJECT\_FILE) , $(PROJECTFILE) , $(PROJECTFILENAME) , $(PROJECT\_FILE\_NAME)  当前编译项目的文件名。
 *  $(PROJECT\_NAME) , $(PROJECTNAME)  当前编译项目的名称。
 *  $(PROJECT\_DIR) , $(PROJECTDIR) , $(PROJECT\_DIRECTORY) , $(PROJECTDIRECTORY)  目前的公共目录编译项目。
 *  $(PROJECTTOPDIR) , $(PROJECT\_TOPDIR) , $(PROJECTTOPDIRECTORY) , $(PROJECT\_TOPDIRECTORY)   目前编译项目的顶层目录中。
 *  $(ACTIVE\_EDITOR\_FILENAME)   文件的文件名在当前活动编辑器中打开。
 *  $(ACTIVE\_EDITOR\_LINE)  返回当前行活动编辑器。
 *  $(ACTIVE\_EDITOR\_COLUMN)   返回当前行的列在活动编辑器。
 *  $(ACTIVE\_EDITOR\_DIRNAME)   当前活动文件的包含目录(相对于普通顶级路径)
 *  $(ACTIVE\_EDITOR\_STEM)   当前活动文件的基本名称(没有扩展)。
 *  $(ACTIVE\_EDITOR\_EXT)   当前活动文件的扩展名。
 *  $(ACTIVE\_EDITOR\_SELECTION)   当前选中的文本从活跃的编辑器。
 *  $(ALL\_PROJECT\_FILES)   一个包含当前项目的所有文件的名称的字符串。
 *  $(MAKEFILE)   makefile的文件名。
 *  $(CODEBLOCKS) , $(APP\_PATH) , $(APPPATH) , $(APP-PATH)   当前运行的实例Code::Blocks的路径
 *  $(DATAPATH公司) , $(DATA\_PATH) , $(DATA-PATH)   当前运行的Code::Blocks的“共享”目录的实例
 *  $(PLUGINS)   当前运行的插件的目录的实例Code::Blocks
 *  $(TARGET\_COMPILER\_DIR)   The compiler installation directory so-called master path.

**构建目标**

*  $(FOOBAR\_OUTPUT\_FILE)   一个 具体的 目标的输出文件。
 *  $(FOOBAR\_OUTPUT\_DIR)   一个 具体的 目标的输出目录。
 *  $(FOOBAR\_OUTPUT\_BASENAME)   一个具体的 目标的输出文件的基本名称(没有道路,没有扩展)。
 *  $(FOOBAR\_PARAMETERS)   一个具体的目标的执行参数
 *  $(TARGET\_OUTPUT\_DIR)   当前的目标的输出目录。
 *  $(TARGET\_OBJECT\_DIR)   当前的目标对象的目录。
 *  $(TARGET\_NAME)   当前的目标的名字。
 *  $(TARGET\_OUTPUT\_FILE)   当前的目标的输出文件。
 *  $(TARGET\_OUTPUT\_FILENAME)   当前的目标的输出文件名。
 *  $(TARGET\_OUTPUT\_BASENAME)   当前的目标的输出文件的基本名称(没有路径,没有扩展名)。
 *  $(TARGET\_CC),$(TARGET\_CPP),$(TARGET\_LD),$(TARGET\_LIB)   当前的目标的构建工具可执行(编译器、链接器等)。
 *  $(TARGET\_COMPILER\_DIR);  当前的目标的构建工具目录(编译器、链接器等)。

**语言和编码**

*  $(LANGUAGE)   The system language in plain language.
 *  $(ENCODING)   The character encoding in plain language.

**Random values**

*  $(COIN)   This variable tosses a virtual coin (once per invocation) and returns 0 or 1.
 *  $(RANDOM)   A 16-bit positive random number (0-65535)

3.设置项目自定义全局变量

设置->全局变量 ->base文本框随便给个路径（如CodeBlock目录）  
右边的用户自定义字段中写入名称和值，比如author = jrvzuo\_qiu  
此时你可以用$\{\#default.author\}定义你的默认代码了，如

/***
     * Filename: $(ACTIVE_EDITOR_STEM).$(ACTIVE_EDITOR_EXT)
     * Author: ${#default.author}
     */

4.关于doxyBlocks插件使用

doxyBlocks插件是调用doxygen来自动生成项目帮助文件，以供后来者快速读懂之前程序员的代码。doxyBlocks功能很强，这里记录些我配置的过程。DoxyBlocks -> open preferences -> 最后的“常规”选项卡。

在此写入doxygen、doxywizard、HHC、Dot路径，前两个从官网下载最新的doxygen程序bin目录（可能要翻墙），HHC指微软的HTML Help Workshop程序目录下的hhc.exe命令行工具，Dot指Graphviz程序bin目录下的dot.exe。HHC可以将HTML文件编译成chm帮助文件，dot“所想即所得”可以将graphviz关系图代码转化成png格式的图片，这里doxyBlocks用它生成UML关系图等然后插入帮助文档。  
配置好上面后，就可以生成帮助文件HTML了。但生成的index.html是英文的，而且没有生成chm格式。以下方法是本人摸索出来，可供参考，\* 为必填。  
确保以下工具存在后，DoxyBlocks ->DoxyWizard打开doxy配置对话框。

\* Step 1的文本框中写入Doxygen工作目录，即/doxygen/bin

Step 2的Wizard选项卡->Topics->Project

\* Project name中写入项目名称

Project synopsis中写入项目摘要描述

Project version or id中写入项目版本

Project log中给张项目Log图片

\* Source code directory中写入源文件目录，如项目中的src文件夹

\* 勾选上Scan recursively 表示递归搜索源文件目录

\* Destination directory中写入生成文档的存放目录，如项目中的desc文件夹  
Wizard->Topics->Mode

Select the desired extraction mode中可选生成的部分，建议All Entities生成所有部分

\* Select programming language to optimize the results for中选择项目语言（doxygen支持多种语言）

Wizard->Topics->Output

勾选上HTML表示生成HTML文档，单选plain HTML表示纯HTML文档，第二个表示带有导航的HTML，第三如果要生成CHM格式文档的话必须选中。

勾选上LaTex表示生成LaTex和PDF文档

勾选上Man pages 生成man帮助文件（linux下帮助文件）

勾选上Rich Text Format及XML生成rtf和xml格式的帮助文件

Wizard->Topics->Diagrams

单选第三个表示使用graphviz生成图表，建议勾选。勾选后的复选建议全部勾选获得完整的图片文件。

Expert->Topics->Project

\* 如果你使用UTF-8文件编码的话，DOXYFILE\_ENCODING一定要写成UTF-8

\* OUTPUT\_LANGUAGE如果你用中文的话，改为Chinese

TAB\_SIZE关于对齐格式，建议为4

Expert->Topics->Build 建议勾选前六个，获得完整的结构文档

Expert->Topics->Input 注意INPUT\_ENCODING是否是UTF-8(否则可能乱码)

Expert->Topics->HTML

勾选上GENERATE\_HTMLHELP表示生成HTML帮助（及chm文件）

CHM\_FILE 填写生成的chm文件名，注意不是路径，仅仅是文件名，如index.chm

HHC\_LOCATION 给出hhc.exe程序的完整路径

CHM\_INDEX\_ENCODING 给出生成索引的编码，建议GBK

建议不要勾选SEARCHENGINE选项，未知错误

Expert->Topics->Dot

勾选上HAVE\_DOT表示生成图表文件

建议勾选上UML\_LOOK 表示生成UML关系图

DOT\_IMAGE\_FORMAT建议只用PNG格式

DOT\_PATH 给出graphviz程序的bin目录

完成以上工作运行，成功生成文档。如果有error: failed to run html help compiler on index.hhp的错误，尝试在管理员权限下输入：

regsvr32 “HTML Help Workshp程序目录\\itcc.dll”

应该能够解决问题。

## 利用Doxyblocks(doxygen)导出生成项目说明文档时出错 ##

[Doxyblocks主页及介绍][Doxyblocks]

[Doxyblocks文档说明][Doxyblocks 1]

codeblocks官网Doxyblocks说明： [http://wiki.codeblocks.org/index.php/DoxyBlocks][http_wiki.codeblocks.org_index.php_DoxyBlocks]

[doxygen主页及介绍][doxygen]

用利用Doxyblocks->Extarct Documents出现以下错误;

Execution of 'doxygen' failed.
    Please ensure that the doxygen 'bin' directory is in your path or provide the specific path in DoxyBlocks' preferences.

需要先安装doxygen，在[http://www.doxygen.nl/download.html)][http_www.doxygen.nl_download.html]下载。

然后在Doxyblocks->open proference->general中配置安装的路径即可。

## 利用Doxyblocks(doxygen)自动生成文件和函数注解 ##

### 自动生成文件注解 ###

settings->edit->Abbreviations 添加fh,内容

/** \file     $ACTIVE_EDITOR_STEM).$ACTIVE_EDITOR_EXT
     *  \author   ${#default.author}
     *  \version  ${#default.version}
     *  \date     $TODAY
     *
     *  \brief    
     *  
     */

其中的author，version是自定义的全局变量（前面已经解释过）。

设置视图：  
![在这里插入图片描述][20190711221832832.PNG]  
在文件头输入fh,ctrl + j自动生成。

显示：

/** \file     wch.h
     *  \author   jsword
     *  \version  1.0
     *  \date     2019-07-11
     *
     *  \brief    宽字符操作函数
     */

### 自动生成函数注解 ###

添加：fn

/*! \fn 
     *  \brief 
     *  \param 
     *  \param 
     *  \exception 
     *  \return 
     */

**吐槽一下，codeblocks并未提供在生成函数注解时，自动获取函数名和参数列表的方法，必须手动输入。**

# 参考文章： #

1.  [使用CodeBlocks编写和Doxygen生成帮助文件][CodeBlocks_Doxygen]
2.  [CodeBlocks变量扩展][CodeBlocks]

**吐槽一下，codeblocks并未提供在生成函数注解时，自动获取函数名和参数列表的方法，必须手动输入。**

[YYYY-MM-DD-hh.mm]: http://YYYY-MM-DD-hh.mm
[Doxyblocks]: http://wxsmithaddons.sourceforge.net/docs/doxyblocks/
[Doxyblocks 1]: http://www.doxygen.nl/manual/index.html
[http_wiki.codeblocks.org_index.php_DoxyBlocks]: http://wiki.codeblocks.org/index.php/DoxyBlocks
[doxygen]: http://www.doxygen.nl/download.html
[http_www.doxygen.nl_download.html]: http://www.doxygen.nl/download.html%29
[20190711221832832.PNG]: /images/20211210/a2bd0101696c4daebb3900cddf1a0c8b.png
[CodeBlocks_Doxygen]: https://blog.csdn.net/jrvzuo_qiu/article/details/60957761
[CodeBlocks]: https://wenku.baidu.com/view/bf4a786ae53a580217fcfe46.html