HTML hyperlink inside @see in Javadoc in Java files fails to render properly

[jbartok]

Describe the bug Following line is not interpreted correctly when in Javadoc in a Java file. Works however properly in Javadoc in Kotlin files:

@see <a href="https://docs.gradle.org/current/userguide/configuration_cache.html">Configuration Cache</a>

See example here (at the end of the class documentation, after the "See also: Provider Factory" part), generated from these sources.

Screenshots

Dokka configuration Generation done via the Dokkatoo plugin 2.3.1, based on Dokka 1.9.20.

[owengray-google]

The kdoc spec for see tags https://kotlinlang.org/docs/kotlin-doc.html#see-identifier says that it only supports links to classes and methods, not URL literals.
I think kdoc should have parity with javadoc (https://docs.oracle.com/en/java/javase/19/docs/specs/javadoc/doc-comment-spec.html#see), which it sounds like it already may in dokka--I think that kdoc spec page should be updated.

[whyoleg]

Hey, thanks for reporting this! During the investigation if it's possible to somehow easy fix it I found several inconsistencies in behaviour of Dokka with KDoc and JavaDoc @see tag: KDoc:

• docs say: @see identifier: Adds a link to the specified class or method to the See also block of the documentation.
• in reality Dokka currently supports @see identifier text and @see[indetifier] text where identifier is DRI (link to declaration)
  • text is optional and is just markdown (can contain links, DRIs, etc) - showed alongside link
  • also we could resolve cases as if there is no identifier at all...
• no external links, no plain text support
• IDEA on the other side supports only @see identifier (what is said in docs) and, for some reason, supports links in a JavaDoc format...

JavaDoc:

• there are 3 formats of links in spec:
  • "plain text" - just plain text (identified by opening quote char ")
  • <a href="...">Label</> - external link (identified by opening angle bracket char <)
  • Type#function label - a.k.a DRI with optional label which should replace Type#function in html label for the link
• Dokka doesn't support fully any of them...
  • for plain text - we still include " (quote) symbols
  • for links - we just show the full html (as this issue says)
  • for DRIs - looks like we support the syntax, but
  • always render it as just Type if it's a link to a function
  • we render label alongside the link, not replacing the name
  • in your example we even drop several of the @see tags because they have the same Type but different functionName
• IDEA support is out of scope here

Dokka implementation details:

• on current moment we render See also as a table with 2 fields in a row: identifier and text
• we do have See class, which represents @see tag for both KDoc and JavaDoc, but is KDoc specific and supports only identifier as DRI
• we do have almost manual parsing of JavaDoc tags which is rather fragile

Possible solutions:

1. (ad-hoc) add a parameter externalAddress: String? and fill it only in case of JavaDoc - then we will need to parse this mini html of a link in javadoc to get the label and the link
2. (ad-hoc) do not add a parameter. If there is html link there, parse it in DocTag and then it will be displayed not in the normal way on the left - but on the right. If we will add additional logic to show it on the left, we may possible support even more undefined behaviours in this regard
3. do nothing now, but resolve all of the issues above, both for KDoc spec vs IDEA vs Dokka inconsistencies and properly support @see tag for both KDoc and JavaDoc consistently in future during KDoc spec design refinements (which are currently started to be real, e.g https://github.com/Kotlin/KEEP/issues/385)

Keeping in mind all this, we don't really want to introduce any more fragile ad-hoc solutions with no clear specification of how it should work having in mind that we have other more important issues to resolve even with Kotlin-only sources with bigger impact. So we would like to stick with the solution number three. Hope this is understandable.