Kotlin Dokka多模块Android项目文档生成问题解析

在Kotlin生态中，Dokka作为官方推荐的文档生成工具，其v2版本（DGPv2）带来了诸多改进。本文将深入分析在多模块Android项目中遇到的文档生成问题及其解决方案。

问题背景

典型的项目结构如下：

项目根目录
    buildSrc
    sample
    lib
        a模块
        b模块 
        c模块

开发团队期望通过lib:dokkaGenerate任务为整个库（包含所有子模块）生成统一文档，但实际生成的文档内容为空。

核心发现

经过排查发现，关键在于buildSrc/build.gradle.kts中是否包含以下依赖：

implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0")

三种典型场景

1. 纯JVM项目
   添加该依赖后文档生成正常，验证了基础功能可行性。

2. Android项目（不添加依赖）
   文档生成结果为空，与预期不符。

3. Android项目（添加依赖）
   产生插件版本冲突：

   插件'org.jetbrains.kotlin.android'版本冲突
   由于插件已存在于classpath但版本未知，无法进行兼容性检查
   

根本原因

问题本质在于插件加载方式的冲突：

• 部分插件通过buildSrc/build.gradle的dependencies添加
• 其他插件通过根目录build.gradle的plugins块添加

这种混合加载方式会导致插件系统无法正确处理依赖关系，特别是对于相互关联的插件组。

解决方案

采用统一的插件加载策略：

1. 完全迁移到buildSrc加载
   将所有插件声明移至buildSrc/build.gradle.kts的dependencies块中

   dependencies {
       implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0")
       implementation("com.android.tools.build:gradle:8.1.0")
       // 其他必要插件...
   }
   

2. 确保版本一致性
   检查所有Kotlin相关插件使用相同版本号

3. 清理构建缓存
   执行./gradlew clean清除可能存在的旧版本插件缓存

最佳实践建议

1. 单一加载源原则
   建议项目统一选择buildSrc或plugins块中的一种方式来加载所有核心插件

2. Android项目特殊处理
   对于Android项目，推荐组合：

   // buildSrc/build.gradle.kts
   dependencies {
       implementation("com.android.tools.build:gradle:x.y.z")
       implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:a.b.c")
       implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0")
   }
   

3. 模块化配置
   对于多模块项目，可以在buildSrc中定义Dokka的公共配置：

   // buildSrc/src/main/kotlin/dokka-convention.gradle.kts
   plugins {
       id("org.jetbrains.dokka")
   }
   
   tasks.dokkaHtml {
       moduleName.set("统一模块名")
       // 其他共享配置...
   }
   

通过以上方案，开发者可以顺利在复杂的多模块Android项目中实现完整的API文档生成，同时保持构建系统的稳定性。