Dokka: Gradle plugin does not play well with gradle-kotlin-dsl

[ramonwirsch]

The methods on DokkaTask all use Groovy Closures, which cannot be implemented in a convenient way from the gradle-kotlin-dsl.

If you use the the Action<Subject> interface provided by gradle, it works with all languages, plus it saves the work of configuring the closure delegate each time, as gradle will handle it for you.

fun externalDocumentationLink(action: Action<in DokkaConfiguration.ExternalDocumentationLink.Builder>)  {
    val builder = ...
    action.execute(builder)
    ...
}

(Providing additional methods with Kotlin lambda functions would make it even more convenient though)
(Also the gradle-kotlin-dsl helpers delegateClosureOf() do generate Closure<Unit> and are also not compatible in kotlin)

[ColinHebert]

Regarding the delegateClosureOf(), you can create your own:

fun <T> Any.dokkaDelegateClosureOf(action: T.() -> Unit) = object : Closure<Any?>(this, this) {
    @Suppress("unused") // to be called dynamically by Groovy
    fun doCall() = org.gradle.internal.Cast.uncheckedCast<T>(delegate).action()
}

[mkobit]

One unfortunate issue with this is that plugins written in Kotlin don't currently get the nice SAM treatment so the Kotlin lambdas might still be useful in the interim - see https://github.com/gradle/kotlin-dsl/issues/522

[sdeleuze]

Hey, gradle/kotlin-dsl#522 seems to be fixed, does that change anything for this issue ? Any chance to move forward on this issue in order to make Dokka usable with Kotlin DSL and make the API discoverable, which seems to me something that should have rather high priority given that Gradle Kotlin DSL 1.0 is approaching? Could you please provide a sample Dokka + Kotlin DSL example in order to avoid blocking people?

[ramonwirsch]

By the look of it, it should now be possible to just declare variants with the Action interface instead of Closure and have that work automatically in Groovy, Java and Kotlin.

[sdeleuze]

Hum, do you know how I am supposed to specify externalDocumentationLink with gradle/kotlin-dsl#522 ?

[ramonwirsch]

The point of this issue was, that the Gradle plugin needs an API change to make it work and according to guide-lines, in the meantime I wrote myself an extension function that you could just throw into buildSrc/

fun DokkaTask.externalDocumentationLink(lambda: DokkaConfiguration.ExternalDocumentationLink.Builder.() -> Unit) {
    val builder = DokkaConfiguration.ExternalDocumentationLink.Builder()
    builder.lambda()
    externalDocumentationLinks.add(builder.build())
}

[sdeleuze]

Ok thanks, I got it working with:

tasks.withType<DokkaTask> {
    outputFormat = "html"
    outputDirectory = "$buildDir/docs/kdoc"
    externalDocumentationLink(delegateClosureOf<DokkaConfiguration.ExternalDocumentationLink.Builder> {
        url = URL("https://docs.spring.io/spring-framework/docs/5.1.0.BUILD-SNAPSHOT/javadoc-api/")
    })
}

Anyway, getting Dokka using Action is still a must have, it is kind of super strange to see that Dokka has the worst Kotlin DSL support of all plugins I use. I have asked on Twitter if somebody can help https://twitter.com/sdeleuze/status/1040899110927261696.

[eskatos]

@semoro, please have a look at #358

[mkobit]

This is available in 0.9.18 (at least in some parts)