Unable to correctly link to classes in a multi module project with non-unique package names

[prempalsingh]

Describe the bug
When using dokkaHtmlMultiModule in a multi-module project with non-unique package names (two different modules can contain the same package name), dokka incorrectly links classes in some other module.

Example -

https://img.ly/docs/vesdk/apidocs/android/v9/pesdk-backend-video-core/ly.img.android.pesdk.backend.model.state/-video-editor-save-settings/index.html

Here, VideoEditorSaveSettings (in module pesdk-backend-video-core) extends from the class SaveSettings (in module pesdk-backend-core). However, if you click on the link for SaveSettings from VideoEditorSaveSettings's documentation (link above), it redirects to https://img.ly/docs/vesdk/apidocs/android/v9/pesdk-backend-adjustment/ly.img.android.pesdk.backend.model.state/-save-settings/index.html

So, basically, it is trying to find SaveSettings in the pesdk-backend-adjustment module instead of pesdk-backend-core. I believe that this might be because the package ly.img.android.pesdk.backend.model.state exists in both pesdk-backend-adjustment and pesdk-backend-core which is somehow confusing dokka?

Expected behaviour
dokka should be correctly able to link to classes in a multi-module project with non-unique package names.

In the example above, clicking on SaveSettings should redirect to https://img.ly/docs/pesdk/apidocs/android/v9/pesdk-backend-core/ly.img.android.pesdk.backend.model.state/-save-settings/index.html

To Reproduce
Mentioned the conditions above. I can create a sample project where the issue is reproducible if needed.

Dokka configuration
Configuration of dokka used to reproduce the bug

apply plugin: 'org.jetbrains.dokka'
./gradlew dokkaHtmlMultiModule

Installation

• Operating system: macOS/Linux
• Build tool: Gradle v6.1.1
• Dokka version: 1.4.30

Are you willing to provide a PR?
Yes, if someone can guide me which part of the code I should look at.

[vmishenev]

This is a known bug #2037

It is a situation where 2 gradle modules have the same package and dokka doesn’t know where to link, so it links to first one. Unfortunately in this case it leads to unresolved link

I hope we will fix this soon.

[IgnatBeresnev]

FYI

Well, the problem is deeper than we think. The Gradle itself has the same issue - gradle/gradle#847. Had it for years now. So, basically, it prevents anybody from naming their subprojects in a way so they share a short name.

Originally posted by @Jeffset in #2437 (comment)

[pbajurko]

@IgnatBeresnev I think you linked two unrelated issues (same gradle's module name vs same java package name in different gradle modules). Hope we don't wait for Gradle's fix for first when we have could fix second in #2901 :)

[IgnatBeresnev]

@pbajurko I believe the underlying technical issue is the same, and fixing either one will hopefully fix all related problems, but of course it needs to be checked.

Modules (subprojects) are processed individually at first, and cross-module link resolution is delayed until all of the modules have been processed. Once all of the modules have generated their individual documentation, one final run is made (in the multi-module mode) that assembles it all together and resolves all of the cross-module links. At this point, I think Dokka simply cannot differentiate between the same package names from different modules, or the same module names from different parents, as relative paths (from the module's root) are the same, while the absolute paths are actually different.

We'll reopen and update the issues if these are indeed different problems, but it'd be nice to reduce the spread of information for now :)

[sdeleuze]

As described in #2913, this is currently Spring Framework Kotlin documentation.

[lppedd]

Having the same issue. A package com.my.pkg.example present in two modules.
Dokka incorrectly links the definition to the module that does not contain it.

Could Dokka implement a way to order modules when building the multi-module documentation?
This seems like a decent workaround.

[IgnatBeresnev]

Upon researching how to fix this bug, it became apparent that there are actually two cases:

1. If the user project has two "local" modules that have non-unique package names, an incorrect link can be generated (to the wrong module). This issue has been fixed in Fix cross module resolution local links #3425 and will be released in Dokka 1.9.20.
2. If the user project is using a 3rd party library that has non-unique package names and whose documentation is hosted externally, an incorrect link can be generated (to the wrong module). This is still relevant and is not trivial to fix, so it will be addressed separately in Generating external link should depend on the module it refers to #3368

The first case is the most common one, so we hope that the majority of problems related to incorrect cross-module links and non-unique package names have been fixed.

The second one is more exotic and is much more difficult to fix, so we'll address it separately and a later date.