search

Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.43k stars 407 forks source link

Broken link to Javadoc in Spring Framework documentation #2913

Open sdeleuze opened 1 year ago

sdeleuze commented 1 year ago

As reported in https://github.com/spring-projects/spring-framework/issues/30091, Spring KDoc documentation contains broken links to Java classes, see for example https://docs.spring.io/spring-framework/docs/current/kdoc-api/spring-tx/org.springframework.transaction.reactive/transactional.html which ends up in a 404 error when following TransactionalOperator.transactional link.

Related link is generated from a reference to the related method in the Kdoc here. I think what happens is that Doka is confused by the fact in Dokka plugin configuration we only generate the Kdoc for Kotlin classes (sourceRoots.setFrom(file("src/main/kotlin"))) not Java ones. But for some reason Dokka generates links that are designed IMO to work if Dokka was used to generate Kdoc for Spring Java classes, which is not the case here because we want on purpose generate only Kotlin specific API documentation.

If no reasonable workaround is possible (I don't want to hardcode Javadoc links in Kdoc), could you please support this I think popular use case in Java + Kotlin projects? The behavior I would expect is Dokka using the https://docs.spring.io/spring-framework/docs/current/javadoc-api/ externalDocumentationLink set when KDoc is not available (in our case when referring to Java classes).

sdeleuze commented 1 year ago

Any chance to solve this to fix Spring Framework Kotlin documentation?

vmishenev commented 1 year ago

could you please support this I think popular use case in Java + Kotlin projects?

Dokka supports it already.

I think the problem is related to https://github.com/Kotlin/dokka/issues/2272. So you have the same package name org.springframework.transaction.reactive in two different projects: java-api and spring-tx.

sdeleuze commented 1 year ago

Indeed, so I will close this one and comment on #2272.

IgnatBeresnev commented 9 months ago

Upon investigating #2272, we found that there are actually two different cases that lead to the same problem. See this comment for more details.

We fixed the first and the most common case, but unfortunately this issue is closer to the second case (#3368) that is much more difficult to fix, and sadly we don't have the capacity to address it in the near future.

Moreover, this issue might actually be even more difficult to fix than #3368, because it tries to link to a declaration that is both local and remote (it's part of the project that Dokka generates documentation for, but the link needs to be external), and it's a mix of Kotlin/Java files which might have different module resolution logic.

For these reasons, I've re-opened this issue as a unique (corner) case.

How severe / annoying is this bug? I'm trying to think if there are other ways or intermediate solutions/hacks that we could come up with in the meantime (with drawbacks, of course), to resolve this problem for Spring specifically.

sdeleuze commented 9 months ago

All Spring Java type links are broken in Spring Kdoc as you can see in the links I linked above, given Spring audience and the fact that Spring Java types are exposed in almost all extensions Spring provides, I would say the impact is pretty severe for Kotlin server-side developers. If you can provide guidance or a PR on how to fix Spring build to workaround this issue, happy to follow/merge related proposal.

sdeleuze commented 5 months ago

See this Spring Framework issue and related commit which fixed it. Could this be fixed in Dokka to work out of the box?