老米爱撸瓦

LuatOS 的 API 文档采用特殊注释格式嵌入在 C/Lua 源码中，通过 apiMaker 工具自动解析生成 Markdown 文档和 VSCode 自动补全文件。

一、文档结构概述

文档注释分为两个层级：

二、模块级字段定义

2.1 基本格式

/*
@module  模块名
@summary 模块简介
@version 版本号
@date    日期
@demo    demo路径
@video   视频链接
@tag     BSP标签
@ready   文档完备状态
@usage
-- 使用示例代码
-- 可以多行
*/

2.2 字段说明

三、API级字段定义

3.1 基本格式

/**
函数简介说明
@api 模块名.函数名(参数1, 参数2, ...)
@tag BSP标签(可选)
@参数类型 参数说明
@参数类型[opt=默认值] 可选参数说明
@return 返回类型 返回值说明
@invalid true
@usage
-- 使用示例代码
local result = 模块名.函数名(1, "test")
 */

3.2 字段说明

四、 示例

4.1 模块示例

/*
@module  adc
@summary 模数转换
@version 1.0
@date    2025.12.07
@demo adc
@tag LUAT_USE_ADC
@ready True
@usage

-- 本库可读取硬件adc通道, 也支持读取CPU温度

-- 读取ADC通道, 返回电压值,单位mV
adc.open(0)
local voltage = adc.get(0)  -- 推荐使用get方法,直接获取计算后的电压值
log.info("adc", "ADC0 voltage:", voltage, "mV")
adc.close(0)

-- 读取CPU内部温度, 单位为0.001摄氏度, 是芯片内部温度, 非环境温度
adc.open(adc.CH_CPU)
local temp = adc.get(adc.CH_CPU)
log.info("adc", "CPU temperature:", temp/1000, "C")
adc.close(adc.CH_CPU)

*/

4.2 API示例

/**
打开adc通道
@api adc.open(id)
@int 通道id,范围0-4，共5个通道可用。除此之外，当id为-1时，表示打开CPU内部温度传感器通道
@return boolean 打开结果成功返回1,失败返回0
@usage
-- 打开adc通道4,并读取
if adc.open(4) then
    log.info("adc", adc.read(4)) -- 返回值有2个, 第一个值为原始值，第二个值为经过内部换算的校准后的电压值
    log.info("adc", adc.get(4))  -- 返回值有1个, 仅计算值
end
adc.close(4) -- 关闭端口
 */
static int l_adc_open(lua_State *L) {
    // 实现代码...
}

4.3 常量示例

//@const CH_CPU number CPU内部温度传感器通道，值为-1
{ "CH_CPU",          ROREG_INT(LUAT_ADC_CH_CPU)},

使用 @_notused_const 标记，不会生成到文档中：

//@_notused_const ADC_RANGE_3_6 number ADC分压电阻开启
{ "ADC_RANGE_3_6",   ROREG_INT(1)},

//@_notused_const CH_VBAT number VBAT供电电压通道(ESP32C3不支持)
{ "CH_VBAT",         ROREG_INT(LUAT_ADC_CH_VBAT)},

五、参数类型说明

5.1 支持的类型标记

5.2 可选参数格式

@int[opt=nil] 可选参数，默认值为nil
@table[opt={}] 可选参数，默认值为空表
@string[opt="default"] 可选参数，默认值为"default"

5.3 多返回值

@return int 原始值,可以用_接收 表示忽略
@return int 从原始值换算得出的实际电压值，单位是mV

五、特殊字段汇总

六、Lua库注释格式

Lua 源文件使用 --[[ 和 ]] 作为注释块标记：

--[[
@module  mylib
@summary 我的库
@version 1.0
@date    2025.12.24
@usage

local mylib = require("mylib")
mylib.test()

]]

--[[
测试函数
@api mylib.test()
@return boolean 成功返回true
@usage
mylib.test()
]]
function mylib.test()
    -- 实现代码
end

七、生成文档

7.1 运行脚本

cd LuatOS/tools/apiMaker
python documentGenerator.py

7.2 输出内容

附录：数据结构说明

文档解析后生成的数据结构：

modules = [
    {
        'module': 'adc',           # 模块名
        'summary': '模数转换',      # 简要描述
        'location': 'luat/modules/luat_lib_adc.c',  # 源文件路径
        'demo': 'demo/adc',        # 示例代码路径
        'video': '',               # 视频链接
        'usage': '-- 示例代码',    # 用法示例
        'tag': 'LUAT_USE_ADC',     # BSP标签
        'version': '1.0',          # 版本号
        'date': '2025.12.07',      # 日期
        'ready': True,             # 文档完备状态
        'const': [                 # 常量列表
            {
                'var': 'adc.CH_CPU',
                'type': 'number',
                'summary': 'CPU内部温度传感器通道',
            },
        ],
        'api': [                   # API列表
            {
                'api': 'adc.open(id)',
                'summary': '打开adc通道',
                'tag': '',
                'args': [
                    {'type': 'int', 'summary': '通道id,范围0-4'}
                ],
                'return': [
                    {'type': 'boolean', 'summary': '成功返回1,失败返回0'}
                ],
                'usage': '-- 示例代码'
            },
        ]
    }
]