i’m trying to apply the Android Dokka plugin, but ...

# dokka

[Chris Overcash]

i’m trying to apply the Android Dokka plugin, but my script is not able to resolve dokkaPlugin. here’s a stripped down version of my project `build.gradle.kts`:

buildscript {
  repositories { maven(url = "<https://internalrepo.com>") }
  dependencies {
    classpath("org.jetbrains.dokka:dokka-base:1.8.10")
    classpath("org.jetbrains.dokka:dokka-gradle-plugin:1.8.10")
    classpath("org.jetbrains.dokka:android-documentation-plugin:1.8.10")
  }
}

allprojects {
  repositories { maven(url = "<https://internalrepo.com>") }
  apply(plugin = "org.jetbrains.dokka")

  dependencies {
    // unresolved reference
    dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:1.8.10")
  }
}

[Chris Overcash]

nvm found it. i was missing this line:
https://github.com/Kotlin/dokka/blob/7a46cd329ac6ccbdb10195310197289947ee4104/exam[…]es/gradle/dokka-versioning-multimodule-example/build.gradle.kts

[Chris Overcash]

https://github.com/Kotlin/dokka/pull/2976

[Joffrey]

The thing is, you probably don't need this line if applying the plugin normally. The only reason you need it is when you use the explicit apply syntax, which probably is only necessary when using an allprojects or subprojects block. And those should be avoided in favor of convention plugins

[Joffrey]

Now I have to say the examples have a lot of non-idiomatic Gradle in the first place

[Chris Overcash]

ah i see. i did have to look around for a while to figure this out, and would like to help anyone in the future avoid that problem

[Ignat Beresnev]

@Chris Overcash thanks for the PR!

Now I have to say the examples have a lot of non-idiomatic Gradle in the first place

Yeah, true...

Problem is, Gradle has many ways to achieve the same thing, and asking people to migrate to convention plugins before they can add Dokka sounds a bit unfriendly to me... If you know how to work with Gradle and you have convention plugins already, you probably don't even need these examples and already know what to do

These example projects and the documentation are primarily for small user projects and libraries that don't have complicated build logic and thus don't even use buildSrc or any other convoluted Gradle features - that's the majority, judging by my experience of looking at projects in which Dokka is used

But it's open source, so I'd be happy to discuss it if you could make the examples more idiomatic, while at the same time not complicating them too much 🙂

Or maybe we could retain these basic Gradle examples and state explicitly that they are for small and basic projects only, and also publish the most idiomatic Gradle example you could have - with convention plugins and so on, and link to it - for those who are willing to go the extra mile.

[Chris Overcash]

@Ignat Beresnev of course! it’s maybe a bit selfish in that i don’t want to have this issue the next time i use Dokka 😄
it’s true our project is multi module and fairly complex, so if this isn’t generally useful i understand. it’s understandable that most projects in the wild using Dokka would be small or at least contained (libraries, example projects, portfolio projects, etc), but there’s probably a good number of closed source enterprise level projects that could benefit (like mine). definitely willing to leave it up to your judgement where and how to document this, if at all.

i’ve been using Gradle long enough that “idiomatic Gradle” seems like a paradox lol. i personally didn’t have much issue with the structure of it, and i am using allprojects and subprojects if that is a factor. if there’s something about my approach that is unidiomatic i’d be happy to learn!

[Ignat Beresnev]

My reply was mostly to @Joffrey’s message 😅 and I hope it didn't come off as a defensive attack - I meant no harm.

It's truly difficult to write beginner-friendly documentation for a Gradle plugin without having to explain Gradle concepts or sending the user to research a bunch of things on their own before they can use the product..

When we migrate our plugin to the idiomatic dokkatoo, we'll need to re-write our Gradle user documentation and correct the examples as well, so if anyone in the community feels like helping with it (review, contributions) - let me know, I'd be happy to work with you 🙂

[Joffrey]

Problem is, Gradle has many ways to achieve the same thing

I totally agree. I'm really not blaming the Dokka maintainers here, the Gradle docs are very unclear as to what is idiomatic or not, and they keep showing seemingly "deprecated" ways in their examples.

asking people to migrate to convention plugins before they can add Dokka sounds a bit unfriendly to me

I disagree here. AFAIR, the examples using allprojects or subprojects are about using Dokka in multi-project builds, and multi-project builds are already more complex. I guess I might just be placing the bar at a different position. I would consider using `allprojets`/`subprojects` a no-go (misleading towards bad practice), but suggesting to place a tiny convention plugin in buildSrc would be acceptable for a simple multi-project setup. So I think it would not be unfriendly but rather helpful to show how people can simply add a little file like buildSrc/src/main/kotlin/dokka-config.gradle.kts and show how to use it.

For example, here is what I did for the gradle-kotlin-publish-plugin, which shows how to use a convention plugin to combine it with other plugins:
https://github.com/joffrey-bion/gradle-kotlin-publish-plugin#example-usage-for-maven-central-publication

[Joffrey]

It's truly difficult to write beginner-friendly documentation for a Gradle plugin without having to explain Gradle concepts or sending the user to research a bunch of things on their own before they can use the product

Right. As a Gradle plugin developer, you should just be expected to document the features of the plugin, not Gradle itself (and there's a fine line here I agree). But we're talking about an example project, in which you can just write something idiomatic if it's not unreasonably complex. Using non-idiomatic things for simplicity is exactly the mistake Gradle makes in their own doc

[Adam S]

I think it’s reasonable/possible to expect the Dokka examples use idiomatic Gradle, but that’s going to be difficult because Dokka Gradle Plugin itself is unidiomatic. And then DGP is unidiomatic because Gradle itself is unidiomatic…

Like, of course the Gradle fans know `allprojects`/`subprojects` is not best practice, but then why aren’t they @Deprecated? A few sentences scattered around the Gradle docs doesn’t really cut it. It feels like a problem with the foundations.

[Joffrey]

I agree, there is definitely a root problem in Gradle itself in terms of deprecation management and docs (and consistency in the docs)

[Adam S]

I should say I’m venting my spleen a bit because I’ve been struggling with Gradle the last few days, and it helps to vent!

[Ignat Beresnev]

I guess I might just be placing the bar at a different position.

I think you are, yeah 😅

The most recently reported problem is the reporter trying to use Kotlin DSL in Groovy scripts, and there were a couple of issues where people didn't even understand to which files they should paste examples from the docs - that's the bar Dokka (as a fundamental tool) has to think about, unfortunately. I don't know if trying to explain idiomatic Gradle will do them any good 😄

The most frequent complaint about Dokka was the old documentation - it was a recurring topic of many UX researches. And if you look at the old docs, I don't think there was anything non-idiomatic. It explained the bare minimum and left the rest to the users, and if you know Gradle - you will certainly manage, no questions. But yeah, documentation was the biggest user problem...

I also did a little experiment when writing the current docs, it was quite eye opening. I had an amazing Kotlin technical writer help me with proofreading the docs, and after staring at the same text for too long you kinda start losing track of things. So I asked her to take this simple multimodule project, take the documentation I wrote, and to do 3 things:

1. Add Dokka to that project and generate documentation
2. Configure Dokka and set suppressObviousFunctions to true for all subprojects.
3. Set documentedVisibilities configuration option to PUBLIC and INTERNAL for one of the subprojects only.
She got stuck and confused after doing the first thing 🙂 I think if you take an average junior/middle developer who doesn't care much for Gradle, you'll see the same result

After that, we added a much of (non-idiomatic) examples and details, and had to explain the difference between single project and multi project builds, and clarify where exactly people should apply what and how

I think the story is a bit different for plugins like detekt - there's no expectation for them to be beginner friendly. And if you need detekt, you are most likely skilled enough to figure it out

[Ignat Beresnev]

But it should be somewhat easier to explain with an idiomatic gradle plugin, yeah. At least there would be no dokkaHtml vs dokkaHtmlMultiModule and DokkaTask vs DokkaTaskPartial confusion like now

[Adam S]

it’s really interesting to read about that research, thanks Ignat

[Adam S]

so when is JetBrains going to do a new version of Gradle, convert it all to Kotlin, and name it after a Russian island starting with ‘H’?

[Ignat Beresnev]

https://www.youtube.com/watch?v=9wtvXoXh0VU▾

[Chris Overcash]

i’m just happy i feel more confident migrating my scripts to Kotlin for now. lack of code insight tools with Groovy is nightmarish

[Ignat Beresnev]

it’s really interesting to read about that research, thanks Ignat

(we're actually planning on doing another UX research for Dokka some time soon. People will be recruited and asked to complete a set of tasks, and then report on it. In our case, we'll pretty much ask them what I asked my colleague to do - add Dokka to a project and configure some things. Of course, it'd be ideal if we could do it with Dokkatoo after spending some time on designing the configuration DSL and addressing known configuration issues/confusions, but we'll see how it goes, maybe we'll do it twice. I'll try not to forget to share the findings)

[Adam S]

i’ve been using Gradle long enough that “idiomatic Gradle” seems like a paradox lol. i personally didn’t have much issue with the structure of it, and i am using allprojects and subprojects if that is a factor. if there’s something about my approach that is unidiomatic i’d be happy to learn!

@Chris Overcash
In a nutshell, problem with `allprojects`/`subprojects` is that they make Gradle work like Maven. And that’s not to say that Maven is a problem, after all it’s a strong build tool too, but it’s not really the way Gradle is supposed to work. Eventually it makes the build config more complicated, and you’ll be missing out on features that make the build faster.

The alternative to allprojects is convention plugins - try taking a look through my answer here. They are an investment, and Gradle is a complete nightmare 50% of the time, but it is really powerful.

[Chris Overcash]

@Adam S awesome. thanks for the lead!
i’ll look into it. for now we’re just using those blocks for spotless and now dokka