https://kotlinlang.org logo
#dokka
Title
# dokka
k

Kirill Gagarski

03/15/2024, 6:27 PM
Hi. I am working on multimodule Gradle project. I noticed that when I browse KDoc comments directly in the code in IDEA, it can resolve links not only to classes on submodule classpath but also across the whole project (i.e. even if the linked class is not a dependency of current submodule, but belongs to the same multimodule project). I wonder if the same behavior is achievable with dokka generated docs. Or is there any chance this will be supported in next versions?
☝️ 1
a

Adam Semenenko

03/18/2024, 1:03 PM
Hi 👋 You can configure Dokka to resolve classes that might not be direct dependencies by defining external links https://kotlinlang.org/docs/dokka-gradle.html#external-documentation-links-configuration
c

CLOVIS

03/18/2024, 1:14 PM
This won't work for other classes in the same build, right? Since it downloads a hosted package list, and you don't have anything hosted when you build locally.
a

Adam Semenenko

03/18/2024, 1:29 PM
Ahh I see, sorry, I misunderstood. For example: • You have subprojects
:project-a
and
:project-b
. • The subprojects are independent, no dependencies between them •
:project-a
has a class with FQN
project.a.A
:project-b
has a class with FQN
project.b.B
• If class
B
has KDoc
[project.a.A]
, then the link is clickable in IntelliJ, but it's not clickable in the generated Dokka docs. Hmm, no, external links won't help with that.
Here's a workaround for the problem described in my previous message. It creates an additional Configuration that you can manually add dependencies to. When generating
:project-b
, Dokka will be able to inspect the classes defined in
:project-a
. In order to be defensive, I set
isTransitive = false
, but that might not be necessary, or not defensive enough!
👀 1
k

Kirill Gagarski

03/19/2024, 8:06 PM
The workaround seems to be working, at least at first glance. I'll try to browse more my generated docs. Using some dumb gradle logic, I cross-added all the subprojects as
dokkaSourceSetClasspath
to each other, I wonder when this approach will shoot me in the leg. I also wonder, can (theoretically) root MultiModule task perform additional resolution of unresolved links to achieve that? Or this is totally out of the scope of this task? Given that the resulting docs are more or less monolythic artifact, this behavior kinda makes sense by default.
c

CLOVIS

03/19/2024, 8:10 PM
I wonder when this approach will shoot me in the leg.
It depends how you wrote it, but at least in theory there shouldn't be any problems except that it will make the documentation generation slower.
can (theoretically) root MultiModule task perform additional resolution of unresolved links to achieve that?
I'm not an expert on the internals of Dokka by far, but my understanding is the root module only combines the partial documentation from all other modules, it cannot really edit their contents to add back links that were not found earlier in the project's phase.
k

Kirill Gagarski

03/20/2024, 6:56 PM
I'm not an expert on the internals of Dokka by far, but my understanding is the root module only combines the partial documentation from all other modules, it cannot really edit their contents to add back links that were not found earlier in the project's phase.
I am no expert as well, but does not it do it for links to dependant modules? Meaning that if
module-a
depends on
module-b
then links in
module-a
docs to
module-b
classes are resolved.
c

CLOVIS

03/20/2024, 7:40 PM
This could be completely wrong, but my understanding is that link resolution happens during the partial module generation, at the module-level. Since a module has access to its dependencies, it can create links to them. Then, at the root level, all links are already done, you just have to combine all the files into a single archive.
This explanation is consistent with the code given above, which adds dependencies on all other projects so each project can resolve all links.
2 Views