2026-05-29

ADC的概念：

ADC就是读出电压

STM32的定时器分：注入通道和规则通道

规则通道：
规则通道相当于你正常运行的程序，看它的名字就可以知道，很规矩，就是正常执行程序

注入通道：
注入通道可以打断规则通道，听它的名字就知道不安分，如果在规则通道转换过程中，有注入通道进行转换，那么就
要先转换完注入通道，等注入通道转换完成后，再回到规则通道的转换流程

工程设置

我们先选择你要用的ADC

配置项	中文说明	可选值 / 含义
IN0-IN9	选择ADC的通道	勾选代表启用通道
Temperature Sensor Channel	内置温度传感器通道	勾选：启用芯片内置温度传感器（通过ADC通道测量内部温度）不勾选：禁用
Vrefint Channel	内部参考电压通道	勾选：启用内部参考电压通道（用于校准和测量供电电压）不勾选：禁用
EXTI Conversion Trigger	外部中断线触发转换	Disable：禁用外部中断触发 EXTI Line X：选择对应的外部中断线作为ADC转换触发源

然后是关于进行配置

ADC 公共设置 ADCs_Common_Settings

配置项	中文说明	可选值 / 含义
Mode	多ADC工作模式	Independent mode：独立模式（各ADC独立工作） Dual/Triple mode：双/三ADC同步/交错模式（多ADC协同工作）

ADC 核心设置 ADC_Settings

配置项	中文说明	可选值 / 含义
Data Alignment	数据对齐方式	Right alignment：右对齐（12位数据存放在寄存器低12位，高位补0） Left alignment：左对齐（12位数据存放在寄存器高12位，低位补0）
Scan Conversion Mode	扫描转换模式	Enabled：开启，按序列扫描多个通道 Disabled：关闭，仅转换单个通道
Continuous Conversion Mode	连续转换模式	Enabled：转换完成后自动重新开始下一次转换 Disabled：单次转换完成后停止
Discontinuous Conversion Mode	不连续转换模式	Enabled：按组分批转换序列通道 Disabled：关闭

规则通道转换模式 ADC_Regular_ConversionMode

配置项	中文说明	可选值 / 含义
Enable Regular Conversions	使能规则通道转换	Enable：开启规则通道转换 Disable：关闭
Number Of Conversion	转换通道数量	1~16，序列中包含的规则通道总数
External Trigger Conversion	外部触发源	Regular Conversion launched by software：软件触发（手动启动） Timer 1/2/3… TRGO：定时器TRGO事件触发 EXTI Line：外部中断线触发
Rank	通道转换顺序	1~16，定义通道在转换序列中的优先级

注入通道转换模式 ADC_Injected_ConversionMode

配置项	中文说明	可选值 / 含义
Enable Injected Conversions	使能注入通道转换	Enable：开启注入通道转换（优先级高于规则通道） Disable：关闭

模拟看门狗设置 WatchDog

配置项	中文说明	可选值 / 含义
Enable Analog WatchDog Mode	使能模拟看门狗	勾选：开启，当通道电压超出阈值范围时触发中断不勾选：关闭

工程代码

初始化ADC

1	HAL_StatusTypeDef HAL_ADC_Init(ADC_HandleTypeDef* hadc)

结构体ADC_HandleTypeDef hadc1;

STM32 HAL ADC初始化结构体参数表

一、ADC_HandleTypeDef 句柄核心成员

参数	数据类型	作用	选项
`hadc1.Instance`	`ADC_TypeDef*`	指定要使用的ADC硬件外设实例	`ADC1`, `ADC2`, `ADC3`(部分型号支持)
`hadc1.Init.ScanConvMode`	`FunctionalState`	扫描转换模式开关控制是否转换多个规则通道	`DISABLE`: 单通道模式 `ENABLE`: 多通道扫描模式
`hadc1.Init.ContinuousConvMode`	`FunctionalState`	连续转换模式开关控制转换完成后是否自动开始下一次	`DISABLE`: 单次转换模式 `ENABLE`: 连续转换模式
`hadc1.Init.DiscontinuousConvMode`	`FunctionalState`	间断转换模式开关仅在扫描模式启用时有效	`DISABLE`: 连续扫描所有通道 `ENABLE`: 分组间断扫描
`hadc1.Init.ExternalTrigConv`	`uint32_t`	ADC转换触发源选择	`ADC_SOFTWARE_START`: 软件触发 `ADC_EXTERNALTRIGCONV_Tx_CCy`: 定时器通道触发 `ADC_EXTERNALTRIGCONV_EXTI_x`: 外部引脚触发
`hadc1.Init.DataAlign`	`uint32_t`	转换结果数据对齐方式	`ADC_DATAALIGN_RIGHT`: 右对齐(推荐) `ADC_DATAALIGN_LEFT`: 左对齐
`hadc1.Init.NbrOfConversion`	`uint32_t`	规则通道组的转换通道总数	`1` ~ `16`(不同型号最大通道数不同)

截图中未出现的重要参数

参数	数据类型	作用	选项
`hadc1.Init.ClockPrescaler`	`uint32_t`	ADC时钟分频系数 ADC最大时钟不得超过36MHz(F1/F4系列)	`ADC_CLOCK_SYNC_PCLK_DIV2`: 2分频 `ADC_CLOCK_SYNC_PCLK_DIV4`: 4分频 `ADC_CLOCK_SYNC_PCLK_DIV6`: 6分频 `ADC_CLOCK_SYNC_PCLK_DIV8`: 8分频
`hadc1.Init.Resolution`	`uint32_t`	ADC转换分辨率分辨率越高精度越高但转换时间越长	`ADC_RESOLUTION_12B`: 12位(默认, 04095) `ADC_RESOLUTION_10B`: 10位(01023) `ADC_RESOLUTION_8B`: 8位(0255) `ADC_RESOLUTION_6B`: 6位(063)
`hadc1.Init.NbrOfDiscConversion`	`uint32_t`	间断模式下每组的通道数仅在`DiscontinuousConvMode=ENABLE`时有效	`1` ~ `8`
`hadc1.Init.ExternalTrigConvEdge`	`uint32_t`	外部触发边沿选择仅在使用硬件触发时有效	`ADC_EXTERNALTRIGCONVEDGE_NONE`: 禁止触发(软件触发时使用) `ADC_EXTERNALTRIGCONVEDGE_RISING`: 上升沿触发 `ADC_EXTERNALTRIGCONVEDGE_FALLING`: 下降沿触发 `ADC_EXTERNALTRIGCONVEDGE_RISINGFALLING`: 双边沿触发
`hadc1.Init.DMAContinuousRequests`	`FunctionalState`	DMA连续请求模式开关仅在DMA模式下有效	`DISABLE`: 单次DMA请求 `ENABLE`: 连续DMA请求
`hadc1.Init.EOCSelection`	`uint32_t`	转换结束标志位选择	`ADC_EOC_SEQ_CONV`: 整个序列转换完成后置位EOC `ADC_EOC_SINGLE_CONV`: 每个通道转换完成后都置位EOC

配置ADC通道

1	HAL_StatusTypeDef HAL_ADC_ConfigChannel(ADC_HandleTypeDef* hadc, ADC_ChannelConfTypeDef* sConfig)

结构体ADC_HandleTypeDef hadc1
结构体ADC_ChannelConfTypeDef sConfig

STM32 HAL ADC通道配置结构体参数表
ADC_ChannelConfTypeDef 规则通道配置结构体

参数	数据类型	作用	选项
`sConfig.Channel`	`uint32_t`	指定要配置的ADC通道号	`ADC_CHANNEL_0` ~ `ADC_CHANNEL_18`(不同型号支持的通道数不同) 包含内部通道：`ADC_CHANNEL_TEMPSENSOR`(温度传感器)、`ADC_CHANNEL_VREFINT`(内部参考电压)、`ADC_CHANNEL_VBAT`(电池电压)
`sConfig.Rank`	`uint32_t`	指定该通道在规则转换序列中的顺序	`ADC_REGULAR_RANK_1` ~ `ADC_REGULAR_RANK_16` 数字越小，转换优先级越高
`sConfig.SamplingTime`	`uint32_t`	指定该通道的采样时间采样时间越长，精度越高但转换速度越慢	`ADC_SAMPLETIME_1CYCLE_5`: 1.5个ADC时钟周期 `ADC_SAMPLETIME_7CYCLES_5`: 7.5个周期 `ADC_SAMPLETIME_13CYCLES_5`: 13.5个周期 `ADC_SAMPLETIME_28CYCLES_5`: 28.5个周期 `ADC_SAMPLETIME_41CYCLES_5`: 41.5个周期 `ADC_SAMPLETIME_55CYCLES_5`: 55.5个周期 `ADC_SAMPLETIME_71CYCLES_5`: 71.5个周期 `ADC_SAMPLETIME_239CYCLES_5`: 239.5个周期
`sConfig.Offset`	`uint32_t`	ADC转换结果偏移量用于校准零点误差，转换结果会自动减去该值	`0` ~ `4095`(12位ADC) 默认值为`0`(无偏移)

其他的函数

STM32 HAL ADC函数参考手册

好的，我已为所有函数补充完整用途说明和所有可能返回值及含义，严格保持你要求的「一个函数一张表」格式，可直接复制到文档使用。

一、初始化与底层函数

`HAL_ADC_Init`

用途：初始化 ADC 外设，根据hadc句柄中的配置参数，配置 ADC 的时钟、工作模式、数据对齐等核心参数。CubeMX 生成代码时会自动调用此函数。
返回值：

HAL_OK：初始化成功
HAL_ERROR：初始化失败
HAL_BUSY：ADC 正忙，无法初始化

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针，指向包含配置信息的结构体	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_DeInit`

用途：将 ADC 外设复位为上电默认状态，关闭 ADC 时钟，释放相关资源。
返回值：

HAL_OK：复位成功
HAL_ERROR：复位失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_MspInit`

用途：ADC 底层初始化函数，由HAL_ADC_Init自动调用。用户需重写此函数，实现 ADC 时钟使能、GPIO 引脚配置、NVIC 中断优先级配置等底层操作。CubeMX 会自动生成此函数代码。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_MspDeInit`

用途：ADC 底层反初始化函数，由HAL_ADC_DeInit自动调用。用户需重写此函数，实现 ADC 时钟关闭、GPIO 引脚复位、中断关闭等操作。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

二、规则通道配置与操作

`HAL_ADC_ConfigChannel`

用途：配置 ADC 规则通道的参数，包括通道号、转换顺序、采样时间和偏移量。可在运行时动态修改通道配置。
返回值：

HAL_OK：配置成功
HAL_ERROR：配置失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`sConfig`	`ADC_ChannelConfTypeDef*`	通道配置结构体指针	自定义结构体，如`&sConfig`

`HAL_ADC_Start`

用途：以轮询（阻塞）模式启动 ADC 规则通道转换。转换过程中 CPU 会被阻塞，直到转换完成或超时。
返回值：

HAL_OK：启动成功
HAL_ERROR：启动失败
HAL_BUSY：ADC 正忙，无法启动

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_Stop`

用途：停止 ADC 规则通道转换，关闭 ADC 外设。
返回值：

HAL_OK：停止成功
HAL_ERROR：停止失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_PollForConversion`

用途：轮询等待 ADC 规则通道转换完成。在轮询模式下，必须调用此函数等待转换结束后才能读取结果。
返回值：

HAL_OK：转换完成
HAL_TIMEOUT：等待超时
HAL_ERROR：发生错误

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`Timeout`	`uint32_t`	等待超时时间，单位为毫秒	`0` ~ `HAL_MAX_DELAY`

`HAL_ADC_PollForEvent`

用途：轮询等待 ADC 指定事件发生，如转换结束事件、溢出事件等。比HAL_ADC_PollForConversion更通用。
返回值：

HAL_OK：指定事件发生
HAL_TIMEOUT：等待超时
HAL_ERROR：发生错误

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`EventType`	`uint32_t`	等待的事件类型	`ADC_EOC_SINGLE_CONV`, `ADC_EOS_CONV`, `ADC_OVR_EVENT`
`Timeout`	`uint32_t`	等待超时时间，单位为毫秒	`0` ~ `HAL_MAX_DELAY`

`HAL_ADC_GetValue`

用途：读取 ADC 规则通道最新的转换结果。转换完成后调用此函数获取原始数据（04095）。
返回值：uint32_t（ADC 转换原始值，范围 04095）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

三、中断模式函数

`HAL_ADC_Start_IT`

用途：以中断（非阻塞）模式启动 ADC 规则通道转换。转换完成后会触发 ADC 中断，自动调用HAL_ADC_ConvCpltCallback回调函数。
返回值：

HAL_OK：启动成功
HAL_ERROR：启动失败
HAL_BUSY：ADC 正忙，无法启动

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_Stop_IT`

用途：停止 ADC 中断模式转换，关闭 ADC 转换完成中断。
返回值：

HAL_OK：停止成功
HAL_ERROR：停止失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_IRQHandler`

用途：ADC 中断服务函数，由 HAL 库内部自动调用。负责处理 ADC 中断，清除中断标志，并调用对应的回调函数。用户无需直接调用此函数，只需在中断向量表中注册即可。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

四、DMA 模式函数

`HAL_ADC_Start_DMA`

用途：以 DMA（直接存储器访问）模式启动 ADC 规则通道转换。转换结果会自动通过 DMA 传输到指定的内存缓冲区，无需 CPU 干预。适合高速、多通道采集场景。
返回值：

HAL_OK：启动成功
HAL_ERROR：启动失败
HAL_BUSY：ADC 或 DMA 正忙，无法启动

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`pData`	`uint32_t*`	数据存储缓冲区地址	自定义数组指针，如`(uint32_t*)adc_buf`
`Length`	`uint32_t`	DMA 传输长度，即一次 DMA 传输的采样次数	`1` ~ `65535`

`HAL_ADC_Stop_DMA`

用途：停止 ADC DMA 模式转换，关闭 DMA 传输。
返回值：

HAL_OK：停止成功
HAL_ERROR：停止失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

五、注入通道函数（高级功能）

`HAL_ADCEx_InjectedStart`

用途：以轮询模式启动 ADC 注入通道转换。注入通道优先级高于规则通道，可在规则通道转换过程中插入转换。
返回值：

HAL_OK：启动成功
HAL_ERROR：启动失败
HAL_BUSY：ADC 正忙，无法启动

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADCEx_InjectedStop`

用途：停止 ADC 注入通道转换。
返回值：

HAL_OK：停止成功
HAL_ERROR：停止失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADCEx_InjectedStart_IT`

用途：以中断模式启动 ADC 注入通道转换。转换完成后会触发中断，调用HAL_ADCEx_InjectedConvCpltCallback回调函数。
返回值：

HAL_OK：启动成功
HAL_ERROR：启动失败
HAL_BUSY：ADC 正忙，无法启动

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADCEx_InjectedStop_IT`

用途：停止 ADC 注入通道中断模式转换。
返回值：

HAL_OK：停止成功
HAL_ERROR：停止失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADCEx_InjectedPollForConversion`

用途：轮询等待 ADC 注入通道转换完成。
返回值：

HAL_OK：转换完成
HAL_TIMEOUT：等待超时
HAL_ERROR：发生错误

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`Timeout`	`uint32_t`	等待超时时间，单位为毫秒	`0` ~ `HAL_MAX_DELAY`

`HAL_ADCEx_InjectedGetValue`

用途：读取 ADC 注入通道的转换结果。
返回值：uint32_t（注入通道转换原始值，范围 0~4095）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`InjectedRank`	`uint32_t`	注入通道序号	`ADC_INJECTED_RANK_1` ~ `ADC_INJECTED_RANK_4`

`HAL_ADCEx_InjectedConfigChannel`

用途：配置 ADC 注入通道的参数，包括通道号、转换顺序、采样时间和偏移量。
返回值：

HAL_OK：配置成功
HAL_ERROR：配置失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`sConfigInjected`	`ADC_InjectedChannelConfTypeDef*`	注入通道配置结构体指针	自定义结构体

六、模拟看门狗函数

`HAL_ADC_AnalogWDGConfig`

用途：配置 ADC 模拟看门狗，设置监控通道和高低电压阈值。当监控通道的转换值超出阈值范围时，会触发中断。
返回值：

HAL_OK：配置成功
HAL_ERROR：配置失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`sAnalogWDGConfig`	`ADC_AnalogWDGConfTypeDef*`	模拟看门狗配置结构体指针	自定义结构体

七、校准与扩展函数

`HAL_ADCEx_Calibration_Start`

用途：启动 ADC 自校准过程。校准可以消除 ADC 的偏移误差，提高转换精度。建议在 ADC 初始化后、首次转换前调用此函数。
返回值：

HAL_OK：校准成功
HAL_ERROR：校准失败

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`SingleDiff`	`uint32_t`	校准模式	`ADC_SINGLE_ENDED`, `ADC_DIFFERENTIAL_ENDED`

`HAL_ADCEx_Calibration_GetValue`

用途：获取 ADC 自校准后的校准值。
返回值：uint32_t（校准值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`
`SingleDiff`	`uint32_t`	校准模式	`ADC_SINGLE_ENDED`, `ADC_DIFFERENTIAL_ENDED`

八、状态与错误查询函数

`HAL_ADC_GetState`

用途：获取 ADC 当前的工作状态，如空闲、忙、转换完成等。
返回值：HAL_ADC_StateTypeDef（ADC 状态枚举值）

HAL_ADC_STATE_RESET：ADC 已复位
HAL_ADC_STATE_READY：ADC 准备就绪
HAL_ADC_STATE_BUSY：ADC 正忙
HAL_ADC_STATE_BUSY_REG：规则通道转换中
HAL_ADC_STATE_BUSY_INJ：注入通道转换中
HAL_ADC_STATE_ERROR：ADC 发生错误

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_GetError`

用途：获取 ADC 发生的错误代码，用于调试和错误处理。
返回值：uint32_t（错误代码）

HAL_ADC_ERROR_NONE：无错误
HAL_ADC_ERROR_OVR：数据溢出错误
HAL_ADC_ERROR_DMA：DMA 传输错误

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

九、回调函数（用户重写）

`HAL_ADC_ConvCpltCallback`

用途：ADC 规则通道转换完成回调函数。在中断或 DMA 模式下，转换完成后 HAL 库会自动调用此函数。用户需重写此函数，在其中处理转换结果。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_ConvHalfCpltCallback`

用途：DMA 半传输完成回调函数。在 DMA 模式下，当传输完成一半数据时，HAL 库会自动调用此函数。常用于双缓冲模式。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADC_ErrorCallback`

用途：ADC 错误回调函数。当 ADC 发生错误（如数据溢出、DMA 错误）时，HAL 库会自动调用此函数。用户需重写此函数进行错误处理。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADCEx_InjectedConvCpltCallback`

用途：ADC 注入通道转换完成回调函数。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

`HAL_ADCEx_LevelOutOfWindowCallback`

用途：模拟看门狗阈值越界回调函数。当监控通道的转换值超出设定的高低阈值范围时，HAL 库会自动调用此函数。
返回值：void（无返回值）

参数	数据类型	作用	选项
`hadc`	`ADC_HandleTypeDef*`	ADC 句柄指针	`&hadc1`, `&hadc2`, `&hadc3`

需要我把 PWM 常用函数 也按这个完全相同的格式（用途 + 返回值 + 参数表）整理一份吗？