嵌入式开发必掌握：文档编写规范实战（代码注释+函数文档+设计文档+API文档）
·
嵌入式开发必掌握：文档编写规范实战（代码注释+函数文档+设计文档+API文档）
标签：嵌入式开发、文档规范、代码注释、Doxygen、设计文档、API文档、用户手册、工程实践
前言
文档是项目的重要组成部分，好的文档能提高代码可读性、降低维护成本、方便团队协作。很多开发者忽视文档编写，导致代码难以理解和维护。
本文将分享完整的文档编写规范，涵盖代码注释规范、函数文档编写、设计文档模板、API文档生成等内容，帮助开发者掌握专业的文档编写能力。
文章主要内容：
- 代码注释规范
- 函数文档编写
- 设计文档模板
- API文档生成
- 用户手册编写
一、代码注释规范
1.1 注释原则
// 注释原则：
// 1. 解释为什么，而不是做什么
// ❌ 错误：i++ // i加1
// ✅ 正确：i++ // 跳过头部字节
// 2. 注释应该有意义
// ❌ 错误：return 0; // 返回0
// ✅ 正确：return 0; // 初始化成功
// 3. 保持注释和代码同步
// 修改代码时，必须更新相关注释
// 4. 避免过多注释
// 代码本身应该清晰易懂，注释用于补充说明
1.2 Doxygen注释格式
/**
* @file main.c
* @brief 主程序入口
* @author Zhang San
* @date 2024-01-01
* @version 1.0
*/
/**
* @brief 初始化系统时钟
* @note 配置外部8MHz晶振，系统时钟72MHz
* @retval None
*/
void SystemClock_Config(void)
{
// 实现代码
}
/**
* @brief 读取ADC通道值
* @param channel ADC通道号（0-15）
* @retval ADC采样值（0-4095）
* @note 采样时间55.5个ADC时钟周期
*/
uint16_t ADC_ReadChannel(uint8_t channel)
{
if(channel > 15)
{
return 0; // 通道号无效
}
// 配置通道
ADC_RegularChannelConfig(ADC1, channel, 1, ADC_SampleTime_55Cycles5);
// 启动转换
ADC_SoftwareStartConvCmd(ADC1, ENABLE);
// 等待转换完成
while(!ADC_GetFlagStatus(ADC1, ADC_FLAG_EOC));
return ADC_GetConversionValue(ADC1);
}
/**
* @brief 计算CRC16校验值
* @param data 数据指针
* @param len 数据长度
* @retval CRC16校验值
* @note 使用Modbus CRC16算法
*/
uint16_t CalculateCRC16(uint8_t *data, uint32_t len)
{
uint16_t crc = 0xFFFF;
for(uint32_t i = 0; i < len; i++)
{
crc ^= data[i];
for(uint8_t j = 0; j < 8; j++)
{
if(crc & 0x0001)
{
crc = (crc >> 1) ^ 0xA001;
}
else
{
crc >>= 1;
}
}
}
return crc;
}
1.3 结构体和宏注释
/**
* @brief 传感器数据结构
*/
typedef struct
{
uint8_t id; /**< 传感器ID */
float temperature; /**< 温度值（℃） */
float humidity; /**< 湿度值（%） */
uint32_t timestamp; /**< 时间戳 */
uint8_t status; /**< 状态：0-正常，1-异常 */
} SensorData_t;
/**
* @brief 系统状态枚举
*/
typedef enum
{
SYS_IDLE = 0, /**< 空闲状态 */
SYS_RUNNING, /**< 运行状态 */
SYS_ERROR, /**< 错误状态 */
SYS_SHUTDOWN /**< 关机状态 */
} SystemState_t;
/** @defgroup GPIO_Pin GPIO引脚定义
* @{
*/
#define GPIO_PIN_0 (1U << 0) /**< GPIO引脚0 */
#define GPIO_PIN_1 (1U << 1) /**< GPIO引脚1 */
#define GPIO_PIN_2 (1U << 2) /**< GPIO引脚2 */
/**
* @}
*/
二、函数文档编写
2.1 函数文档模板
/**
* @brief 函数功能简述
*
* @details 函数功能详细描述，可以多行
* 说明函数的实现原理、算法等
*
* @param param1 参数1说明
* @param param2 参数2说明
*
* @retval 返回值说明
*
* @note 使用注意事项
* @warning 警告信息
* @see 相关函数
*
* @code
* // 使用示例
* uint16_t result = FunctionName(param1, param2);
* @endcode
*/
uint16_t FunctionName(uint8_t param1, uint16_t param2)
{
// 实现
}
2.2 实际示例
/**
* @brief 配置UART串口参数
*
* @details 配置UART的波特率、数据位、停止位、校验位等参数，
* 并使能UART外设时钟和GPIO时钟
*
* @param USARTx UART外设指针（USART1/USART2/USART3）
* @param baudrate 波特率（如115200）
* @param wordlength 数据位长度（8位或9位）
* @param stopbits 停止位（1位或2位）
* @param parity 校验位（无校验、奇校验、偶校验）
*
* @retval 0: 配置成功
* @retval 1: 参数错误
*
* @note 调用前需确保GPIO已正确配置
* @warning 波特率不能超过外设最大速率
*
* @code
* // 配置USART1：115200, 8N1
* UART_Config(USART1, 115200, UART_WORDLENGTH_8B,
* UART_STOPBITS_1, UART_PARITY_NONE);
* @endcode
*/
uint8_t UART_Config(USART_TypeDef *USARTx,
uint32_t baudrate,
uint16_t wordlength,
uint16_t stopbits,
uint16_t parity)
{
// 参数检查
if(USARTx == NULL)
{
return 1;
}
// 配置实现
USART_InitTypeDef USART_InitStructure;
USART_InitStructure.USART_BaudRate = baudrate;
USART_InitStructure.USART_WordLength = wordlength;
USART_InitStructure.USART_StopBits = stopbits;
USART_InitStructure.USART_Parity = parity;
USART_InitStructure.USART_Mode = USART_Mode_Rx | USART_Mode_Tx;
USART_InitStructure.USART_HardwareFlowControl = USART_HardwareFlowControl_None;
USART_Init(USARTx, &USART_InitStructure);
USART_Cmd(USARTx, ENABLE);
return 0;
}
三、设计文档模板
3.1 软件设计文档模板
# 软件设计文档
## 1. 文档信息
| 项目 | 内容 |
|-----|------|
| 项目名称 | 智能温控系统 |
| 文档版本 | V1.0 |
| 作者 | 张三 |
| 日期 | 2024-01-01 |
## 2. 系统概述
### 2.1 系统功能
- 多通道温度采集
- PID温度控制
- OLED显示
- 数据存储
### 2.2 性能指标
- 温度范围：0-100℃
- 控制精度：±0.5℃
- 响应时间：<30s
## 3. 系统架构
### 3.1 硬件架构
- MCU：STM32F103C8T6
- 传感器：NTC热敏电阻
- 显示：OLED 128x64
- 存储：W25Q16 Flash
### 3.2 软件架构
- RTOS：FreeRTOS
- 任务数量：6个
- 通信接口：UART、I2C、SPI
## 4. 模块设计
### 4.1 温度采集模块
- 功能：ADC采集温度传感器数据
- 接口：float GetTemperature(void)
- 采样周期：100ms
### 4.2 PID控制模块
- 功能：PID算法计算控制量
- 接口：float PID_Calculate(float error)
- 控制周期：500ms
## 5. 接口设计
### 5.1 函数接口
见API文档
### 5.2 数据结构
见数据结构定义
## 6. 测试方案
### 6.1 单元测试
- 测试温度采集精度
- 测试PID算法正确性
### 6.2 集成测试
- 测试系统整体功能
- 测试性能指标
3.2 接口设计文档
# 接口设计文档
## 1. UART接口
### 1.1 数据格式
- 波特率：115200
- 数据位：8位
- 停止位：1位
- 校验位：无
### 1.2 协议格式
| 字段 | 长度 | 说明 |
|-----|------|------|
| 帧头 | 2字节 | 0xAA 0x55 |
| 长度 | 1字节 | 数据长度 |
| 命令 | 1字节 | 命令码 |
| 数据 | N字节 | 数据内容 |
| 校验 | 2字节 | CRC16 |
| 帧尾 | 2字节 | 0x55 0xAA |
### 1.3 命令列表
| 命令码 | 功能 | 数据格式 |
|-------|------|---------|
| 0x01 | 设置目标温度 | 温度值（2字节） |
| 0x02 | 查询当前温度 | 无 |
| 0x03 | 查询系统状态 | 无 |
四、API文档生成
4.1 Doxygen配置文件
# Doxyfile配置示例
# 项目信息
PROJECT_NAME = "Embedded Project"
PROJECT_NUMBER = "1.0"
OUTPUT_DIRECTORY = "docs"
# 输入文件
INPUT = src include
FILE_PATTERNS = *.c *.h
# 输出格式
GENERATE_HTML = YES
GENERATE_LATEX = NO
# 提取信息
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
# 源码浏览
SOURCE_BROWSER = YES
INLINE_SOURCES = YES
# 图形生成
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
4.2 生成文档
# 生成HTML文档
doxygen Doxyfile
# 文档位置
docs/html/index.html
五、用户手册编写
5.1 用户手册模板
# 用户手册
## 1. 产品介绍
### 1.1 产品功能
本产品是一款智能温控系统，具有以下功能：
- 实时温度监测
- 自动温度控制
- 参数设置
- 数据记录
### 1.2 技术参数
- 工作电压：DC 5V
- 工作温度：0-50℃
- 控制范围：0-100℃
- 控制精度：±0.5℃
## 2. 使用说明
### 2.1 系统连接
1. 连接电源适配器
2. 连接温度传感器
3. 连接加热/制冷设备
4. 打开电源开关
### 2.2 参数设置
1. 按SET键进入设置模式
2. 按UP/DOWN键调整参数
3. 按SET键确认保存
4. 按ESC键退出设置
### 2.3 正常使用
1. 系统上电自动运行
2. OLED显示当前温度
3. 系统自动控制温度
4. 可通过串口远程控制
## 3. 故障排除
### 3.1 常见问题
**问题1：温度显示异常**
- 检查传感器连接
- 检查传感器是否损坏
- 重启系统
**问题2：控制失效**
- 检查加热/制冷设备
- 检查PWM输出
- 检查PID参数
## 4. 技术支持
如有问题，请联系技术支持：
- 邮箱：support@example.com
- 电话：400-xxx-xxxx
六、总结与互动
6.1 核心要点总结
- 代码注释：使用Doxygen格式，解释为什么
- 函数文档：包含参数、返回值、示例
- 设计文档：清晰描述系统架构和模块设计
- API文档：使用Doxygen自动生成
- 用户手册：面向用户，通俗易懂
6.2 实战经验总结
- 文档和代码同步更新
- 注释要有意义，不要废话
- 函数文档要完整，包含示例
- 设计文档要清晰，便于理解
- 用户手册要通俗，面向用户
智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。
更多推荐
3
0- 0
已为社区贡献11条内容
所有评论(0)