Dokka v2迁移指南：配置项变更与解决方案

背景概述

Dokka作为Kotlin生态中广泛使用的文档生成工具，在v2版本中进行了重大架构调整。本次升级引入了更符合Gradle最佳实践的DSL配置方式，但同时也带来了部分配置项的迁移挑战。

核心配置变更点

任务配置方式重构

v1版本中常见的tasks.withType<DokkaTask>().configureEach写法已被简化为顶层dokka扩展。这种改进使配置更加直观，但需要注意：

// v1旧写法
tasks.withType<DokkaTask>().configureEach {
    suppressInheritedMembers = true
}

// v2新写法
dokka {
    publications.configureEach {
        suppressInheritedMembers = true
    }
}

废弃参数处理

1. failOnWarning参数
   该参数在v2中已被移除，建议通过Gradle的--continue参数或自定义构建逻辑实现类似功能。

2. externalDocumentationLink配置
   外部文档链接的配置方式已改为更类型安全的DSL：

// 新版本推荐写法
externalDocumentationLinks {
    create("gradle") {
        url.set(URI.create("https://docs.gradle.org/current/javadoc/"))
    }
}

迁移实践建议

1. 配置项分层
   v2版本明确区分了全局配置(dokka { })和出版物级配置(publications.configureEach { })，建议按功能域组织配置。

2. 版本兼容性
   当同时指定apiVersion时，需确保与项目的Kotlin编译器版本匹配。

3. 输出目录设置
   路径配置现在支持Gradle的Provider API，更符合现代Gradle实践：

outputDirectory.set(layout.projectDirectory.dir("../docs/api"))

常见问题解决方案

对于从v1迁移的项目，若遇到未文档化的配置项，建议：

1. 检查Gradle构建扫描中的弃用警告
2. 查阅新版DSL的源码定义
3. 在出版物级别和源集级别分别尝试配置

通过以上调整，可以顺利完成到Dokka v2的迁移，同时获得更健壮、更可维护的文档构建配置。新版本虽然存在短暂的适应成本，但其改进的DSL设计和更强的类型安全性将为长期维护带来显著收益。