Reference code from package markdown

[MariusVolkhart]

Is your feature request related to a problem? Please describe
I'm using a .md file to document my package, as described at https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation

I am explaining how classes in the package fit together, and am linking to the classes when mentioning them. The linking seemingly must be done via standard markdown linking. For example, [MyClass](./-my-class). This is error prone and tedious, as refactoring easily breaks the link and the link is not verified during Dokka compilation.

Describe the solution you'd like
I'd like the functionality of the [] element linking mechanism present in KDoc. For the previous example, [MyClass] should link to the MyClass element of the package I am describing.

[MariusVolkhart]

This becomes much worse when referencing CAPITAL_CASE constants. The link becomes [./-my-class/-m-y-_-c-o-n-s-t-a-n-t.html]

[rnett]

Seconding this. Would be nice to have IDE autocompletion, too, but that's not a Dokka issue.

[glureau]

[MyClass] should link to the MyClass element of the package I am describing.

Maybe to be more generic, we could have the qualifier name, so that a package can still define a reference to class from another package while not targeting the local class. Something like [MyClass](org.stuff.MyClass). So that this kind of link can be defined from anywhere and not just from a package definition.

I'm afraid Dokka cannot check in advance if there is a file at this name (because plugins could generate files later), so we could have collision if a file named "org.stuff.MyClass" exists. In this case maybe we need a marker to be explicit, like [MyClass](class://org.stuff.MyClass). What do you think?

[IgnatBeresnev]

What you're describing can be done via https://github.com/Kotlin/kotlinx-knit

Please refer to kotlinx.coroutines and kotlinx.serialization which utilize knit for the same use case as you described :)

[glureau]

Thanks! Trying to understand knit, looks like it generates files to be commited so I need a specific branch and build strategy with CI having authorization to commit... just to make a link to the documentation? (I suppose I could generate code without commiting it thought...) Or is it possible to just define knit.code.include so that [launch] is defined based on this include? (sorry the documentation wasn't clear for me)

If yes, we can work with that but it feels like an additional work that could be directly provided by Dokka, right?

[IgnatBeresnev]

looks like it generates files to be commited so I need a specific branch and build strategy with CI having authorization to commit

Similar to binary-compatibility check, there are two tasks - one generates files/changes to be commited, and one (knitCheck) actually checks if these files match the current layout. So it will fail the build if files are not up-to-date. This way, problems can be resolved before merging them by whoever made the changes.

Not sure what you would need a specific branch and a build strategy for... sorry if I misunderstood you :)

it feels like an additional work that could be directly provided by Dokka, right?

Sure, but it doesn't look like Dokka is going to have that feature anytime soon, especially since knit can do that

[strangesource]

I just found out by coincidence that this seems to work now in 1.8.10. 🎉

You can reference a class by doing the following in your module description:

[Class](org.stuff.MyClass)

Unsure when exactly this was fixed.

[IgnatBeresnev]

Wow, turns out, it's been working since at least Dokka 1.6.0:

Both

Module/package description linking to [com.example.MyClass]

and

Module/package description linking to [MyClass](com.example.MyClass)

@strangesource thanks for letting everyone know!

This should be extremely useful for #2914.

Not sure if it's a bug or a feature though 😅 If it's a feature, it's worth documenting and writing tests for it. I'll mark it with tech-debt for now so that we get back to it some time later

[strangesource]

Worth mentioning that it also works in multi module setup. 🙂 As expected you can link from one module description (module A) to a class from a different module (module B) if the one module depends on the other (A depends on B). The other way round does not work.