基于Doxygen_C语言代码文档一键生成的记录与规范(嵌入式适用)

下位机代码格式规范整合记录

1. 注册 doxygen 账号获取doxygen 的 *.exe 执行文件

https://pan.baidu.com/s/1MF5v-Ts80BysmZtXSqONmg 提取码:l4br

1. 进入Graphviz 首页下载Graphviz 软件*.mis 安装包  (可不选,但推荐)

https://pan.baidu.com/s/1lIhc31LUvZNVK75r9ghtNA 提取码：12wo

安装.安装完成后:

1. 打开Doxygen GUI frontend ,配置文档格式

依次点击其中的红框 完成Doxygen 工作空间文件夹

Project name 填写上所属项目名称:一般命名为keil 项目名称.

如有版本控制,添加project version

Project Loge 可添加可不添加

选择源码所在文件夹,并勾选递归扫描文件夹

选择Doxygen 输出在哪个文件夹 输出文件请在项目下新建一个Dox文件夹.

修改模式以支持C语言:

点击mode 修改成以下选项

修改输出文件为HTML或 .CHM

点击 Output 主要选择HTML下方 输出Plain Html 如果想选择.chm格式,需要电脑中有chh.exe 执行文件.

可选: 确认是否添加类型关系图:

点击 diagram 需要电脑中安装Graphviz 用处是可以使类型关系图像化 但是会使数据量变得很大,如果不要,勾选 No diagrams

修改输出语言为中文:

点击 Expert->Project 选择OUTPUT_LANGUAGE 为Chinese,同时生成*.chm文件时会出现乱码.原因不明.

设置导出部分包含的函数:

点击 Expert->Build->将其中选项设置成下图所示:

修改.c/.h文件编码 默认以UTF8 格式读入 同时可以添加额外的源码文件夹

点击Input 可以添加你想要另外源码文件夹 同时 编辑你的文件编码格式 一般keil中默认 ANSI 编码格式. 但是这里不能识别 ,我们这里填写 GB2312 , 如果有另外的根据自身.c/.h 文件编码格式设置(一般为 GB2312 或UTF8)如果不行还有 GBK   格式  GB18030 格式 如果再不行查看那个文件出错了,去看看下他的格式到底是什么.

点击Source Browser-> 是否显示源码在Html 中

运行查看结果:

保存 Doxygen配置文件,下次使用时只需复制此文件放入相应文件夹修改输入输出文件夹即可.

另存为任意格式,这里我自定义了一种格式 Dof格式,实际任何格式都可以

Doxygen 注释格式:(不完全统计)

　　0. 注释文件.c/.h:

/**

************************************************************************************************

* @file 所在文件名.c/.h

* @brief 这里写函数简介

* @verbatim

这里填写这个文件的用法,引用,注意事项,详细简介.可能引发的BUG 在这里写入的东西会原封不动的显示在生成的文档中

@endverbatim

* @author 这里填写公司名字

* @version 版本号(选填.)

* @note 标记版权,出处 感谢,想法等

***********************************************************************************************

*/

1. 注释函数:

/**

***********************************************************************************************

* @brief 这里写函数简介

* @param 传参变量名1 解释这个参数 如果你传入了一个结构体或者枚举量可以使用 @see 结构体名

* @param 传参变量名2 解释这个参数

* @return 返回类型

* @author 作者名 邮箱@地址 方便认知,索源;

* @note 记下这个函数可能出现的各种状况等等

**********************************************************************************************

*/

在注释中使用 @see 表示 你可以参考某个结构体,枚举量,函数等.那么Doxygen会自动为其添上超链接跳转.

添加作者信息使用 @author

添加时间信息使用 @since

添加要办的事项 @todo

添加标记出来已知但是未解决的bug @bug

例如:

/**

***********************************************************************************************

* @brief 通过ID 寻找到学生并修改TA的名字

* @param stu_id 系统自动赋值的id,有且仅有一个,u32 类型 @see u32

* @param name 你想要设置的名字字符串 当name为NULL 时可能出现错误

* @return Studen* 如果输入id 非法那么返回NULL 否则返回修改之后指向该学生的指针.

* @note 通过快速寻找获得学生的ID 在复制其名字给该学生,时间复杂度较低.

***********************************************************************************************

*/

Student * Student_SetName(u32 stu_id,char* name)

{

///< @bug 出现空指针时将会出现错误

///< @todo 解决空指针出现异常的问题

}

1. 结构体成员信息注释,枚举量注释,行注释

两种:      ///< 你要注释的内容

/**< 你要注释的内容 */

为保证未来可能对块注释造成影响,我们使用第一种. ///< 你要注释的内容

例如:

typedef sturuct

{

u32 student_id; ///< 系统自动分配的ID号 可作为学号

char studentName[50]; ///< 学生名字 最大不可超过49个字符 aka: 24个汉字

GENDER gender; ///< 性别 具体参见:@see GENDER

} Student;

另:参考ST公司标准库文件命名方法.

对函数命名提出规范:(待商议)

一组.c/.h文件有一个固定的单词缩写作为在该文件内的所有前缀.

Eg: GPIO_PIN_0;GPIO_readPin(GPIOA,GPIO_PIN_0);

假定我们有 motor.h/.c 文件 定义 所有函数,全局变量 ,宏定义 都要在前加上 Motor_

①　函数 命名规范:使用小驼峰命名法,动词在前,名词在后;

例如motor.c中设置某个电机的速度: Motor_setSpeed(uint16_t speed);

②　结构体/类 命名规范:使用大驼峰命名法;

例如motor.c 中配置电机参数的结构体: Motor_CfgMotorInitStruct;

③　全局变量 命名规范: 采用小驼峰命名法;

uint32_t Motor_SpeedNow;

④　宏定义常量 命名规范: 全部大写易发生歧义的地方使用下划线隔开

例如: 定义最大速度: #define MOTOR_MAX_SPEED 600000

⑤　宏定义函数 命名规范: 参考函数命名规范

例如: #define Motor_delayMs(msec)  OS_tickDelay( (msec*1000) )

⑥　缩写规范:

为方便书写 可以将必要的单词进行缩写,但是在缩写时 必须要在定义添加上行注释 写上 全称并解释,方便开发人员记忆

例如:   char* Motor_cml; ///< ComMent Line 注释行

#define CUP_CNT ///< cup count  杯子的总值

⑦　定义变量时的语法规范: 在定义全局 类型时:

1. 1. 定义结构体:一律使用:typedef 进行定义 同时结构体内部成员变量命名参考小驼峰命名法

typedef struct

{

int maxSpeed; ///< 最大的速度

u8 (*readPin)(GPIO_Type* GPIOx,GPIO_Pin_Type GPIO_PIN_x);     ///< 读取IO状态的指针函数

} Motor_CfgMotorInitStruct;

1. 1. 定义枚举类: 每一个枚举类的值应该被指定 且由小到大排列 ,方便后期打印排查错误时可以快速核对

typedef enum

{

Motor_StatusOk = 0, ///< 正常 且 空闲

Motor_StatusErr = 1, ///< 发生错误,不可被调用

Motor_StatusBusy = 2 ///< 无错 但忙,不可被调用

} Motor_Status;

1. 1. 定义共用体: 参考定义结构体;

⑧　定义局部变量:

定义局部变量时 i , j , k, 指定用来迭代数组

局部变量全部使用小写,不加文件前缀.

局部变量的命名应当简介明了

⑨　if / for /while / #if 需要注释的地方

1. 1. 如果一个花括号里面的语句很多,那么在花括号结束的地方应当有注释标记;

例如:

Motor_Status motorstatus;

if(motorstatus == Motor_StatusOk)

{

//这里有很多语句

...

//  if (motorstatus == Motor_StatusOk) over;

}else if(motorstatus == Motor_StatusOk)

{

}

1. 1. 如果条件判断 多且复杂,那么应该在花括号开始的地方 添加注释

if(  (motorstatus == Motor_StatusOk || motorstatus != Motor_StatusBusy) &&

motorstatus != Motor_StatusErr)

{//如果 电机不出错且不再忙的状态

//@todo

}else if(motorstatus == Motor_StatusOk)

{

}

1. 1. 宏判断 应该添加的注释:

在#if #ifdef #ifndef 与之对应的#endif 后添加注释 中间间隔嵌套的尤其应该如此

例如:

#ifndef  _MOTOR_H_

#define _MOTOR_H_

#endif //#ifndef  _MOTOR_H_

附带Doxygen 各项设置说明书:

Project：

DOXYFILE_ENCODING	Doxygen文件的编码方式，默认为UTF-8，若希望支持中文，最好设置为 GB2312。
PROJECT_NAME	Project 的名字，以一个单词为主，多个单词请使用双引号括住。
PROJECT_NUMBER	Project的版本号码。
OUTPUT_DIRECTORY	输出路径。产生的文件会放在这个路径之下。如果没有填这个路径，将会以目前所在路径作为输出路径。
OUTPUT_LANGUAGE	输出语言, 默认为English 。
JAVADOC_AUTOBRIEF	若设为 YES，doxygen将会使用一个 JavaDoc 风格的注释，作为简明描述来表述第一行（直到第一行结束）。
SEPARATE_MEMBER_PAGES	若设为 YES，doxygen 将为每一个成员建立一个新页，若设为 NO，成员文档将成为文件/类/名字空间文档中的一部分。像MSDN那样右边每页显示一个函数，把这个选项选中，这样每个函数就是一个页。
TAB_SIZE	主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版。
OPTIMIZE_OUTPUT_FOR_C	这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。
SUBGROUPING	这个选项选择后，输出将会按类型分组。

Build：

EXTRACT_ALL	为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释，但是private和static函数不属于其管制。
EXTRACT_PRIVATE	是否解析类的私有成员。
EXTRACT_STATIC	是否解析静态项。
EXTRACT_LOCAL_CLASSES	是否解析源文件（cpp文件）中定义的类。
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的存在，所以这个选项没有必要使用。

Input：

INPUT	指定加载或找寻要处理的程序代码文件路径。这边是一个表列式的型态。并且可指定档案及路径。举例来说若您有a.c, b.c, c.c 三个档案。您可使用INPUT = a.c, b.c, c.c 的方式。若您给定一个目录，该目录下面所有档案都会被处理。
FILE_PATTERNS	如果您的INPUT Tag 中指定了目录。您可以透过这个Tag来要求Doxygen在处理时，只针对特定的档案进行动作。例如：您希望对目录下的扩展名为.c, .cpp及.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h。
INPUT_ENCODING	用于指定doxygen解析源文件所使用字符编码，doxygen内部使用UTF-8编码，同样也是默认的输入编码，若希望支持中文，最好设置为 GB2312。
RECURSIVE	这是一个布尔值的Tag，只接受YES或NO。当设定为YES时，INPUT所指定目录的所有子目录都会被处理。需要递归处理子目录。
EXCLUDE	如果您有某几个特定档案或是目录，不希望经过Doxygen处理。您可在这个Tag中指定。
EXCLUDE_PATTERNS	类似于FILE_PATTERNS的用法，只是这个Tag是供EXCLUDE所使用。

Source Brower：

SOURCE_BROWSER	如果设定为YES，则Doxygen会产生出源文件的列表，以供查阅。
INLINE_SOURCES	如果设定为YES，则函数和类的实现代码被包含在文档中。
STRIP_CODE_COMMENTS	忽略普通的文档注释。
REFERENCED_BY_RELATION

Index：

ALPHABETICAL_INDEX

如果设定为YES，则一个依照字母排序的列表会加入在产生的文件中。（有很多类、结构等项时建议设为YES）。

HTML：

GENERATE_HTML	若设定为YES ，就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。
HTML_OUTPUT	HTML文件的输出目录。这是一个相对路径，所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。
HTML_FILE_EXTENSION	HTML文件的扩展名。预设为.html。
HTML_HEADER	要使用在每一页HTML文件中的Header。如果没有指定，Doxygen会使用自己预设的Header。
HTML_FOOTER	要使用在每一页HTML文件中的Footer。如果没有指定，Doxygen会使用自己预设的Footer。
HTML_STYLESHEET	您可给定一个CSS 的设定，让HTML的输出结果更完美。
GENERATE_HTMLHELP	如设定为YES，Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。是否生成压缩HTML格式文档（.chm）。
CHM_FILE	表示输出的chm文件路径。
GENERATE_CHI	表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。
TOC_EXPAND	表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。像MSDN那样在左边的树中显示函数列表。若为 YES，可在HTML 帮助文档的目录和树型查看器中增加额外组成员的条目。
GENERATE_TREEVIEW	若设定为YES，Doxygen会帮您产生一个树状结构，在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。
TREEVIEW_WIDTH	用来设定树状结构在画面上的宽度。

LaTex：

GENERATE_LATEX	设定为YES 时，会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX 的相关工具。
LATEX_OUTPUT	LaTeX文件的输出目录，与HTML_OUTPUT用法相同，一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。
LATEX_CMD_NAME	LaTeX程序的命令名称及档案所在。预设为latex。

RTF：

RTF_OUTPUT

与HTML_OUTPUT 用法相同，用来指定RTF 输出档案路径。预设为rtf。

Man：

GENERATE_MAN	若设定为YES ，则会产生Unix Man Page 格式的说明文件。
MAN_OUTPUT	与HTML_OUTPUT 用法相同，用来指定Man Page的输出目录。预设为man。

XML：

GENERATE_XML

若设定为YES ，则会产生XML 格式的说明文件。

Preprocessor：

ENABLE_PREPROCESSING	若设定为YES ，则Doxygen 会激活C 的前置处理器来处理原始档。
PREDEFINED	可以让您自行定义一些宏。类似于gcc 中的-D选项。

Dot：

CLASS_DIAGRAMS	这个标记用来生成类继承层次结构图。要想生成更好的视图，可以从 Graphviz 下载站点下载dot工具。
HAVE_DOT	如果这个标记设置为 Yes，doxygen 就使用dot工具生成更强大的图形，比如帮助理解类成员及其数据结构的协作图。注意，如果这个标记设置为Yes，<CLASS_DIAGRAMS> 标记就无效了。
CLASS_GRAPH	如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图。
GRAPHICAL_HIERARCHY	设置为YES时，将会绘制一个图形表示的类图结构。
UML_LOOK	若为 YES，doxygen将生成继承和协作的图表，在样式类似于 OMG 的统一建模语言。
CALL_GRAPH	若 CALL_GRAPH，HAVE_DOT都为 YES，doxygen 将被每一个全局函数或类方法生成一个调用依赖图。
CALLER_GRAPH	若 CALLER_GRAPH，HAVE_DOT 都为 YES，doxygen 将被每一个全局函数或类方法生成一个被调用的依赖图。
HIDE_UNDOC_RELATIONS	若为 YES，如果目标未被文档化或者不是一个类，那么继承和协作图中将隐藏继承和调用的关系。
COLLABORATION_GRAPH	若 COLLABORATION_GRAPH，HAVE_DOT 都为 YES，doxygen 将为每个文档化的类生成一个协作图，显示直接和间接的类与其他文档化类的执行依赖关系（继承，包容，类引用变量）。
DOT_PATH	指定 dot 工具放置的位置，若选项后留空，则假定dot 工具处于能被查找到的路径之下。
DOTFILE_DIRS	用于指定文档中包含一个或多个保存有 dot 文件的目录。

Keil(MDK)设置快捷补全 快捷键 ctrl + shift + space 触发文本补全

Edit->Configuration->Text Complet

(所有关键字均可自定义.)

新建一个关键字为 filefile 内容为:

/**

************************************************************************************************

* @file |___FILENAME_c_FILENAME_h

* @brief Remark_the_file_introduction______it_is_block_comment_

* @verbatim

* Detailed_description_of_the_document

* @endverbatim

* @author DESINPRO Co. Ltd;

* @version V0.0

* @note CopyRight By XXXX Co. Ltd All right reserve

************************************************************************************************

*/

新建一个关键字为function 内容为:

/**

***********************************************************************************************

* @brief |___take_introduction_of_this_Function

* @param param1                 Explanation_theParam

* @param param2

* @return Return_Value_Type    Explanation_theReturn

* @author Take_your_email_Address

* @note Remark_What_this_function_might_encounter

**********************************************************************************************

*/

新建一个关键字为cml    (Comment line)内容为:

///< |

新建一个关键字为todo  内容为:

///< @todo |

新建一个关键字为bug 内容为:

///< @bug |

替换关键字struct 内容为:

/**

***********************************************************************************************

* @brief |___Remark_the_struct_introduction______it_is_block_comment_

* @verbatim

* Detailed_description_of_the_struct

* @endverbatim

* @author Take_your_email_Address

* @note Remark_What_this_function_might_encounter

***********************************************************************************************

*/

typedef struct

{

// Edit struct_menber;

} |TypeDef;

替换关键字 enum 内容为:

typedef enum

{

// Edit enum_menber;

} |TypeDef;