Gradle Dokka无法重复执行及多模块项目异常问题求助

我来帮你解决这两个在多模块Gradle项目中用Dokka时碰到的头疼问题——我之前在团队项目里也踩过类似的坑，摸索出了一些靠谱的解决办法：

问题1：Dokka非要依赖构建产物（jar），明明源码都在还报错 #

默认情况下，Dokka会傻等着依赖模块的jar任务输出，但咱们多模块项目里如果没提前构建那些jar，它就直接报错，这确实反直觉。核心解决思路就是让Dokka直接用源码，别盯着编译后的jar不放。

你可以在根项目或者每个子模块的构建脚本里这么配置：

Groovy版配置示例 #

tasks.named('dokkaHtml') {
    // 让Dokka依赖所有子模块的主源码集，跳过jar依赖
    dependsOn(subprojects.sourceSets.main.allSource)
    // 确保依赖模块的Dokka任务先执行，保证文档生成顺序
    subprojects.each { subproject ->
        if (subproject.plugins.hasPlugin('org.jetbrains.dokka')) {
            dependsOn(subproject.tasks.named('dokkaHtml'))
        }
    }
    // 配置源码路径，让Dokka能找到所有子模块的源码
    configuration {
        sourceLink {
            localDirectory = file("src/main/kotlin")
            remoteUrl = null // 不需要远程源码链接就设成null
            remoteLineSuffix = null
        }
        subprojects.each { subproject ->
            sourceLink {
                localDirectory = subproject.file("src/main/kotlin")
                remoteUrl = null
                remoteLineSuffix = null
            }
        }
    }
}

Kotlin DSL版配置示例 #

tasks.named<DokkaHtmlTask>("dokkaHtml") {
    // 关联所有子模块的主源码，不依赖jar产物
    dependsOn(subprojects.flatMap { it.sourceSets.main.get().allSource })
    // 让子模块的Dokka任务先跑完，避免依赖问题
    subprojects.forEach { subproject ->
        if (subproject.plugins.hasPlugin("org.jetbrains.dokka")) {
            dependsOn(subproject.tasks.named<DokkaHtmlTask>("dokkaHtml"))
        }
    }
    // 配置所有子模块的源码链接，确保Dokka能解析到
    configuration {
        sourceLink {
            localDirectory = file("src/main/kotlin")
            remoteUrl = null
            remoteLineSuffix = null
        }
        subprojects.forEach { subproject ->
            sourceLink {
                localDirectory = subproject.file("src/main/kotlin")
                remoteUrl = null
                remoteLineSuffix = null
            }
        }
    }
}

这么一改，Dokka就会直接去读源码，再也不会因为没jar就报错了。

问题2：删了文档目录后跑Dokka，啥输出都没有 #

这十有八九是Gradle的增量构建在搞鬼——它觉得任务的输入没变化，就直接跳过执行了。这里有两个靠谱的解决办法：

办法1：用官方的清理任务代替手动删除 #

Dokka自带了cleanDokka任务，专门用来清理文档输出目录，比你手动删靠谱多了。下次要重新生成文档，直接跑：

./gradlew cleanDokka dokkaHtml

这样Gradle能正确感知到输出目录被清理，就会重新执行Dokka任务了。

办法2：调整任务的输入输出配置，让Gradle能追踪变化 #

如果非要手动删目录，那你得给Dokka任务明确标记输出目录，确保Gradle能监控它：

// Kotlin DSL示例
tasks.named<DokkaHtmlTask>("dokkaHtml") {
    outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
    // 可选：如果还是有问题，可以强制Gradle不跳过任务，但不建议长期用，会影响构建速度
    // outputs.upToDateWhen { false }
}

另外，你可以用这个命令检查Dokka任务的输入是否正确包含了所有源码：

./gradlew dokkaHtml --info | grep "Input file"

如果发现某些源码没被列进去，就得在Dokka配置里手动添加这些路径，让Gradle能追踪到源码的变化。

额外的实用建议 #

1. 统一管理多模块文档：在根项目建一个dokkaMultiModule任务，把所有子模块的文档聚合到一起，管理起来更方便：

   // Kotlin DSL 根项目build.gradle.kts
   tasks.register<DokkaMultiModuleTask>("dokkaMultiModule") {
       outputDirectory.set(layout.buildDirectory.dir("dokka/multiModule"))
       subprojects.forEach { subproject ->
           dependsOn(subproject.tasks.named<DokkaHtmlTask>("dokkaHtml"))
       }
   }
   

2. 升级Dokka版本：很多旧版本的增量构建和依赖解析问题已经在新版本里修复了，尽量用最新版的插件。在根项目的settings.gradle.kts里更新：

   plugins {
       id("org.jetbrains.dokka") version "1.9.10" apply false
   }
   

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