Linking to a package in Javadoc using @see renders weirdly

[nea89o]

Describe the bug
I have a java file, which in the Javadoc for the containing file contains an @see other.package directive.
This directive is parsed by Dokka and generates a "See also" section, however the content of that section are not a link, and are also broken into two separate lines. Similarly the @link directive gets ignored / turned into a regular non-link text segment.

Expected behaviour
I would expect the contents of the see also section to contain a clickable link to the package content overview for that package, and to not break apart the package name.

Screenshots

To Reproduce
ConfigAccordionId.java from the screenshot:

package io.github.moulberry.moulconfig.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 *
 * Test link: {@link io.github.moulberry.moulconfig.test}. End of link.
 *
 * @see io.github.moulberry.moulconfig.test
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@Deprecated
public @interface ConfigAccordionId {
	int id();
}

Dokka configuration
Configuration of dokka used to reproduce the bug

// Plugin: 
id("org.jetbrains.dokka") version "1.8.10"

// Task config: 
tasks.dokkaHtml {
    dokkaSourceSets {
        create("main") {
            moduleName.set("MoulConfig")
            sourceRoots.from(sourceSet.main.get().allSource)
            classpath.from(tasks.compileJava.get().classpath)

            includes.from(fileTree("docs") { include("*.md") })

            sourceLink {
                localDirectory.set(file("src/main/"))
                remoteUrl.set(URL("https://github.com/NotEnoughUpdates/MoulConfig/blob/$hash/src/main/"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

Installation

• Operating system: Linux
• Build tool: Gradle v7.5
• Dokka version: 1.8.10

Additional context
I've had similar problems linking to a package overview from a markdown file using

See the [annotations](io.github.moulberry.moulconfig.annotations) documentation

Are you willing to provide a PR?
Sure

[IgnatBeresnev]

It looks like Dokka is unable to resolve package names in @see, and the default behaviour for unresolved links is to just dump it as text (better than nothing), so that explains what's happening

For the Java part

Java's javadoc is able to parse and render such links correctly, they lead to the package's description page, so it can be considered to be a bug from that perspective (Dokka is likely not following the javadoc spec)

For the Kotlin part

Whether Dokka should support linking to packages using Dokka's @see tag is a good question. The documentation for @see states:

Adds a link to the specified class or method to the See also block of the documentation.

There's no mention of linking to packages, but IntelliJ IDEA resolves such links successfully, so there's inconsistency which leads to understandable confusion...

I'll add the kdoc-spec tag to keep this in mind.

[nea89o]

As noted in the Additional Context section, i also cannot get markdown files to resolve package links. Because of markdown files having widely different behaviour depending on which flavour one uses, I didn't want to call it a bug (might just me not understanding the format), but could it be that linking to a package in general just does not work? I could only test java @see and {@link } for now, but i guess setting up a kotlin project with dokka should not be more complicated than java 🙃 (which was already really easy).

[IgnatBeresnev]

i also cannot get markdown files to resolve package links

It's pretty much the same thing under the hood, so I'm 99% certain it doesn't work in Kotlin either, hence the tag :)

[IgnatBeresnev]

Also applies to linking to packages from KDoc text, for example:

• [org.trc.language.parser]
• [blub](org.trc.language.parser)

This is useful if package documentation contains some information that the author wants to refer the users to.