Display actual class names instead of <ERROR CLASS>

[cjbrooks12]

When the project classpath is not provided to Dokka, references to classes in other libraries are displayed as <ERROR CLASS>. For projects using the Gradle plugins to run Dokka, this is fine since they are able to properly provide the classpath to Dokka, but for running Dokka on the CLI directly from its fat jar, or for trying to use Dokka as a library as I do for Kodiak/Orchid, this makes it very difficult to use as intended.

I don't fully understand the internals of how Dokka parses the Kotlin files, but it seems like Dokka should be able to simply output the String value of that class reference instead of completely erroring out, since that String is just a part of the source code and can be deduced just by reading that single file, without needing to look anything up from the classpath. Since this is documentation, even an unlinked String for a type name is better than <ERROR CLASS>.

[cjbrooks12]

I think I've got a fix for this. I'll open a PR shortly for review

[semoro]

It is not possible in case of implicit function/property type

fun returnsUnresolvedString() = ""

Here is impossible to get proper name for return type of such function

[cjbrooks12]

Yeah, that's what I had found as well, but I was able to fix it for the majority of cases.

However, after a bit more digging, I found that I was able to get the entire expression as a String directly from the PSI tree. Maybe we could just render that whole raw expression directly into the docs? It's not ideal, as none of its types will be linked, but it will still be better than simply display an error message. I could update my PR with this new finding.

[semoro]

It is not clear, why you even want to run Dokka with incorrect configuration and get something?

[cjbrooks12]

I'm building a documentation site generator that has functionality to wrap Dokka and embed that data in a custom theme (think Jekyll, but with plugins for code documentation). To do this, I am running Dokka as a fatjar on the command-line with a custom formatter that renders the Dokka models as JSON, which can then be used by Orchid to render that data in theme templates.

The reason I am trying to fix this and get it displayed properly is that I am not running Dokka from Gradle, and thus am unable to provide the complete configuration Dokka expects. In fact, a big feature of Orchid is that it is not tied directly to any build system, and so could be used for things like one repo cloning several others and documenting them all from one place. The most common use-case for using Orchid is to set it up in a single docs subproject and point it to your other modules in a repo, rather than having Orchid set up for each individual module. This makes it really nice for aggregating documentation from many different projects into a single website with minimal configuration, but it also means that it cannot easily access the classpath of those other modules it is documenting.

It turns out that it is pretty difficult to get the classpath if you're not tied directly into each individual Gradle project (especially in the case of Android). As an example, Acorn is an Android project documented with Orchid, and this line is clearly missing data in the rendered site. Ideally, the return type of that function would be visible and linked to the Android documentation for ViewGroup, but since Orchid cannot provide the classpath to Dokka, nothing is shown. The only way to understand that method is to look at the actual source file to see what text is there.

What I am proposing with this issue/PR is that in the case that Dokka is unable to provide the property types for a method because it does not have the classpath it needs, to still output the source text that is there. By outputting the text from the AST instead of simply <ERROR CLASS>, that method above can still be understood without looking at the entire source file. This is the behavior that is used with Orchid's other documentation integrations (Java, Groovy, and Swift); none of those other tools need any kind of context in order to run properly and give me a model I can effectively work with.

[malachid]

We even see this on
https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/run-blocking-test.html

[asm0dey]

Folks, we're hitting it too, like this: https://kotlin.github.io/kotlin-spark-api/kotlin-spark-api_3.3.0_2.13/org.jetbrains.kotlinx.spark.api/as.html

It looks really bad cause enduser can't understand what's written there at all