Anyone else find Dokka amazing, and yet frustratin...

# dokka

[Mike]

Anyone else find Dokka amazing, and yet frustrating? The lack of documentation and good examples is the big thing.

Anyway, perhaps someone else has figured this out.

Using the approach as per above in a project. Then I realized that for the most part, my samples ARE unit tests, so why not use my unit tests directly? Less repetition and less to maintain.

BUT as soon as I add my test folder to the samples configuration, Dokka ALSO insists my tests be documented.

It doesn’t do this if the samples are in a different project (using Gradle for build).

Anyone else experienced this and figured out a way to work around it?

[semoro]

There is some info on https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/samples/ReadMe.md

If Dokka insists that samples should be documented it is a bug, or kind of misconfiguration like you provided it not only in samples but in sources also

[semoro]

Anyway, could you please create issue on github, so we will investigate what’s the case
Just checked repository you provided and found nothing suspicious in first look. So might be a bug in Dokka

[Mike]

Will investigate further and report accordingly. Thank you.

[Mike]

Hmm, would appear to be a problem with the project’s configuration somehow. When I try to duplicate the issue in my simple demo project, I can’t.

So will have to dig deeper, but as you suspected, it is most likely a configuration issue somewhere in my Gradle build/plugins being used…

[Mike]

Was able to duplicate after all so created https://github.com/Kotlin/dokka/issues/452

Let me know if you require anything further, or have suggestions.

[Mike]

For the samples, I tried writing my samples like that, but don’t see how the assertPrints etc gets converted to the output I see in the Kotlin docs. The page says

when the sample is transformed to be embedded in docs, these assertions are either replaced with…

But I’m not seeing that happen. Is there some pre-processor in the libraries’ build pipeline that I’m not seeing, or perhaps some configuration for Dokka, or I’m not generating the docs with the correct type?

[semoro]

There is some special processing in Dokka pipeline

[semoro]

But you can implement your own, or reuse current
See https://github.com/Kotlin/dokka/blob/master/core/src/main/kotlin/Samples/KotlinWebsiteSampleProcessingService.kt
https://github.com/Kotlin/dokka/blob/e94df7be47eef5b8305c291037a6b15852647eb8/core/src/main/kotlin/Formats/StandardFormats.kt#L47

[semoro]

You can define your own format with this sample processor

[Mike]

Thank you I'll take a look.