Hey :wave: We are currently updating the dokka examples inside the <kotlin-examples> repoistory. Is ...

# dokka

[Sebastian Sellmair [JB]]

Hey 👋
We are currently updating the dokka examples inside the kotlin-examples repoistory.
Is there anything you are interested in? Any configuration that we should show? The current PR only shows very basic examples.

https://github.com/Kotlin/kotlin-examples/pull/127

[gildor]

Why default example shows how to do that for custom configuration? I think it's relatively rare case when project which uses doka doesn't have Kotlin plugin
I would instead show as simple as possible configuration for standard project (a single module Kotlin library project where the main use case is publish kdoc and javadoc for maven cental)

[Zach Klippenstein (he/him) [MOD]]

Would also be helpful to have a sample for generating a single site for a multi-module library project, as well as a separate config for generating individual javadoc jars for the same project (eg aggregated site as Markdown, individual artifacts as javadoc HTML). I would think this is a common use case for open source libraries with multiple modules that want to publish API docs via something like mkdocs.

[Sebastian Sellmair [JB]]

Why default example shows how to do that for custom configuration?

I do not 100% get that, since the only custom thing we do in this default examples is to create a sourceLink. MPP projects are not yet auto-configured by dokka

use case is publish kdoc and javadoc for maven cental)

There is no more configuration necessary for html and javadoc formats. Applying the dokka plugin is will automatically create tasks like :dokkaHtml or dokkaJavadoc 👍

Would also be helpful to have a sample for generating a single site for a multi-module library project,

Good idea! We should definitely show how multi-module projects can be configured.

[Zach Klippenstein (he/him) [MOD]]

Maybe a sample of using externalDocumentationLink as well? Took me a bit of trial and error to get this working to link to official Android docs, for example.

[gildor]

no more configuration necessary

But you have to register task to maven-publish plugin, right?

[Sebastian Sellmair [JB]]

Maybe a sample of using externalDocumentationLink as well?

Agree! 👍

Took me a bit of trial and error to get this working to link to official Android docs, for example.

Yes.. I am not quite happy with some parts of the configuration DSL. It is definitely planned to improve this after the milestone release. Sharing all your frustrations will help us!

But you have to register task to maven-publish plugin, right?

Oh! Yes, you're right. I just focused on generating javadoc, but people want to push this as artifact. Maaaybe we should also ship some "dokkaJavadocJar" task out of the box? 🤔

[Zach Klippenstein (he/him) [MOD]]

I vote yes for the dokka javadoc jar task!!

[Sebastian Sellmair [JB]]

I mean sure: This should not be the job of dokka, right? I mean creating this package can easily be done with gradle APIs, buuuut on the other hand: This should be as simple as possible to work with, soooo...

[Zach Klippenstein (he/him) [MOD]]

Would be great if the samples pointed out that you have to manually add a dependency on assemble tasks for dokka to work (it would be even better if the plugin did this automatically, but I think there's already an issue for that).

[Zach Klippenstein (he/him) [MOD]]

This should not be the job of dokka, right?

Maybe technically, but the fact that javadoc "just works" (at least I believe it does, in the sense that dependencies and assembly work out of the box for maven publishing) but dokka doesn't makes it seem like it's not supported as well.

[Sebastian Sellmair [JB]]

Hmm? It should not be necessary to run assemble first in order to make dokka work? Could tell me which issue you are referring to?

Regarding the jar tasks:
Good argument in my opinion. As I said: All of this should be as easy as possible!

[Zach Klippenstein (he/him) [MOD]]

Filed a bug for the assemble issue, I'll add a repro project and the exact error message in a sec: https://github.com/Kotlin/dokka/issues/1116

[Zach Klippenstein (he/him) [MOD]]

Also filed a couple other configuration issues I've noticed re: subprojects: https://github.com/Kotlin/dokka/issues/1114, https://github.com/Kotlin/dokka/issues/1113

[Zach Klippenstein (he/him) [MOD]]

I filed the maven issue as well: https://github.com/Kotlin/dokka/issues/1117

[Zach Klippenstein (he/him) [MOD]]

It should not be necessary to run assemble first in order to make dokka work?

My bad, I just realized this is probably a jetifier bug, not a dokka one.

[Joe]

an updated multi-module maven/pom.xml example would also be appreciated

[Afzal Najam]

Using custom plugins example would be nice. And also maybe how to use the KotlinAsJava plugin