I apologise in advance if this is a stupid query, ...

# dokka

[Jacob Wingate]

I apologise in advance if this is a stupid query, but I am encountering an issue where dokkaHtml is populating elements that lack KDoc annotations, including a "Package-level declarations" section. My understanding was that only KDoc-annotated code should be included by default, but this does not seem to be the case in my project.

I have attached an example showing the "Package-level declarations" being generated without corresponding KDoc annotations.

Below is my current build.gradle configuration:

tasks.dokkaHtml {
    dokkaSourceSets {
        named("main") {
            sourceRoots.from(file("src/main/kotlin"))
            displayName.set("Main Documentation")
            suppress.set(false)
            reportUndocumented.set(false) // Exclude undocumented elements

        }
        named("test") {
            sourceRoots.from(file("src/test/kotlin"))
            displayName.set("Test Documentation")
            suppress.set(false)
            reportUndocumented.set(false)

        }
    }
}

Any help would be greatly appreciated!

[glureau]

My understanding was that only KDoc-annotated code should be included by default

I think it's a wrong assumption. Dokka is supposed to expose a developer api, so everything that is visible from a developer using the library.

reportUndocumented.set(false) // Exclude undocumented elements

From documentation: Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they have been filtered by documentedVisibilities and other filters.
So that's only saying at dokka to not warn, it doesn't exclude the undocumented elements.

[CLOVIS]

Hey! The package-level declarations is just the list of things in a package. Each package has its own.

If you want, you can add custom text in that page, as explained here. You can't remove the page. (except by writing a custom format plugin)

[Jacob Wingate]

Thank you both for your feedback—it has been incredibly helpful! I’ve found that my assumptions are often incorrect, as I’m only nine months into a programming career change and very much in the deep end, though I’m enjoying the process.
Ultimately, I’m looking for a high-level "presentation mode" to annotate and share what certain elements (primarily tests) of our codebase are doing for our clients. I initially thought KDoc/Dokka might be a good fit, but it seems more detailed in its "presentation mode" than what we need.
Would either of you happen to know of any other annotation or presentation solutions that come to mind? Again, I apologise if this is a misguided approach!

[glureau]

Mkdocs can help you generate a website from markdown files. I guess most of your documentation could be in markdown files, so if you only cares about "manual documentation" (not generated from code) it's fine.

Maybe too advanced for you now but for sharing knowledge, I'm currently generating several markdown files from tests (UT which are writing files in /build directory) and k2d (KSP scanning kotlin code and producing markdown files), aggregating them with grip (alternative of knit) and serving them with mkdocs. For more visual rendering, I use mermaidjs inside of those markdown files. I can't share too much of the results unfortunately (private company) but it's a very good communication tool.

[Jacob Wingate]

Wow! Thank you for you gracious sharing. A bit for me to unpack here (and liaise with team members on) but I feel what you have offered up here is pretty close to what we are looking for.

I hope to pay this forward someday Mr glureau :)

[CLOVIS]

Note that there is a mermaidjs Dokka plugin, in case that's useful

[Jacob Wingate]

Thanks Ivan - very helpful. Cheers!