如何在Dokka中创建嵌套列表？Kotlin文档格式问题咨询

我之前也踩过这个坑，Dokka官方文档确实没把“列表”单独拎出来做针对性说明，但其实它完全兼容标准CommonMark的列表语法，下面给你一步步演示怎么实现你要的效果：

1. 基础编号列表写法 #

在KDoc注释里，直接用数字加.开头就能创建顶层编号列表，注意每行要跟在注释的* 后面：

/**
 * 基础编号列表示例：
 * 1. 初始化配置文件
 * 2. 加载数据源
 * 3. 执行核心业务逻辑
 */
fun processData() {}

2. 添加项目符号子列表 #

要给编号项嵌套子列表，只需要给子项缩进4个空格（或1个制表符），并用- 开头即可：

/**
 * 带嵌套子列表的编号列表：
 * 1. 初始化配置文件
 *    - 读取本地config.yaml配置
 *    - 验证配置项合法性
 *    - 加载默认 fallback 配置
 * 2. 加载数据源
 *    - 建立MySQL数据库连接
 *    - 缓存高频查询结果
 * 3. 执行核心业务逻辑
 */
fun complexProcess() {}

3. 实现顶层编号的正确续接 #

如果中间需要插入说明文字再继续列表，直接手动指定后续的编号就行，Dokka会自动识别连续的编号序列：

/**
 * 编号续接完整示例：
 * 1. 初始化配置文件
 *    - 读取本地config.yaml配置
 *    - 验证配置项合法性
 * 
 * 配置加载完成后，开始处理数据源：
 * 2. 加载数据源
 *    - 建立MySQL数据库连接
 *    - 缓存高频查询结果
 * 
 * 最后执行核心业务逻辑：
 * 3. 执行核心业务逻辑
 *    - 过滤无效数据
 *    - 生成统计报表
 */
fun fullProcess() {}

关键注意事项 #

• 子列表的缩进必须和父项的内容对齐，不能和注释的*对齐，否则会被识别成新的顶层列表
• 如果你嫌手动写数字麻烦，也可以全部用1. 开头，Dokka会自动帮你转换成连续的数字（不过手动指定编号可读性更强）
• Dokka底层用的是CommonMark解析器，所以所有标准Markdown列表语法都适用，比如有序列表的1./a./i.风格，无序列表的-/*/+风格

内容的提问来源于stack exchange，提问作者0xbe5077ed