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

标签：两种   lsp   members   rem   并且   sources   html   说明书   名字空间   

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

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：

Build：

Messages：

Input：

Source Brower：

Index：

HTML：

LaTex：

RTF：

Man：

XML：

Preprocessor：

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;

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

标签：两种   lsp   members   rem   并且   sources   html   说明书   名字空间   

原文地址：https://www.cnblogs.com/kimalittlestar/p/10290441.html