“Streamlined Dokka Integration: Multi-Module Projects with Versioning Plugin” in Android

Dokka is an invaluable tool for Kotlin developers, simplifying the process of generating comprehensive documentation from code comments. It stands out for its native support of Kotlin syntax, ensuring accurate documentation for Kotlin projects. Additionally, Dokka seamlessly integrates with mixed-language projects, allowing for the consolidation of documentation from both Java and Kotlin files. Its versatility extends to multiple output formats, including HTML, Javadoc, and Markdown, catering to various documentation needs. With its user-friendly interface and ongoing support from JetBrains, Dokka enhances project maintainability, fosters collaboration, and ultimately streamlines the documentation process for Kotlin projects.

What are KDoc and Dokka used for?

In Java programming, Javadoc is commonly used to document Java code. Before Dokka, there wasn’t a suitable tool for documenting Kotlin code. Dokka is a documentation tool similar to Javadoc, but it’s designed to work with both Kotlin and Java. Dokka’s documentation is powered by a language called KDoc.

KDoc is the language used to document Kotlin code. Good documentation requires proper commenting, and KDoc makes this easier by allowing the use of block tags and Markdown. KDoc is essentially a plugin used within Android Studio to assist with documentation. To use KDoc:

• Start KDoc comments in a class with /** and end with */.
• KDoc supports block tags and inline Markdown, allowing for additional information to be added to elements using the @ symbol.
• @receiver: document receiver extension
• @param: documents properties of class or functions with name and description
• @see: documents link to a specified class or function

How to implement dokka plugin in kotlin multimodule android project ?

To utilize Dokka, the initial step involves adding a dependency within the project’s Gradle file at the project level.

classpath "org.jetbrains.dokka:dokka-gradle-plugin:1.9.20"

For documenting Gradle multi-module projects, we can utilize the dokkaHtmlMultiModule tasks.

The DokkaHtmlMultiModule task depends on all Dokka tasks within the subprojects. It executes these tasks, generating a top-level page that includes links to all the generated documentations, whether they originate from subprojects or not.

Once this dependency is added, it’s necessary to apply Dokka plugin to each module that requires documentation for your project.

apply plugin: 'org.jetbrains.dokka'

DokkaHtmlMultiModule task in Groovy(build.gradle)

dokkaHtmlMultiModule{
String currentVersion = "2.0"
String previousVersionsDirectory = file(previousVersionsDirectory)
moduleName.set("DemoProject")

String versionConfiguration = """ 
{
"version" = "$currentVersion",
"olderVersionDir" = "$previousVersionsDirectory",
"renderVersionsNavigationOnAllPages" = "true"
}
"""

String baseConfiguration = """ 
{
"customAssets" = ["${file("documentation/logo-icon.svg")}"],
"footerMessage" = "© 2024 -Ezzy Learning"
}
"""
pluginMapConfiguration.set(
[
"org.jetbrains.dokka.versioning.VersioningPlugin": versionConfiguration,
"org.jetbrains.dokka.base.DokkaBase": baseConfiguration
])

}

DokkaHtmlMultiModule task in Kotlin(build.gradle.kts)

val currentVersion = "2.0"
val previousVersionsDirectory = project.rootProject.projectDir.resolve("previousDocVersions").invariantSeparatorsPath

tasks.dokkaHtmlMultiModule {
    pluginConfiguration<VersioningPlugin, VersioningConfiguration> {
        version = currentVersion
        olderVersionsDir = file(previousVersionsDirectory)
        moduleName.set("DemoProject")
    }
    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
        customAssets = listOf(file("documentation/logo-icon.svg"))
        footerMessage = "© 2024 -Ezzy Learning"
    }
}

When you add the ‘dokkaHtmlMultiModule’ task in your project level build.gradle, it will generate documentation for your project. To execute Dokka, utilize the following command, or alternatively, access it through Gradle tasks and initiate it by clicking on it:

./gradlew dokkaHtmlMultiModule

Here is an example of generated documentation :

To enable versioning (project version dropdown) in your project’s documentation, add the following dependency to your build.gradle or build.gradle.kts file:

dependencies {
dokkaHtmlMultiModule('org.jetbrains.dokka:versioning-plugin:1.920')
}

This addition ensures that versioning functionality is integrated seamlessly into your documentation. To simplify and improve readability, consider creating a separate Gradle task for dokka and applying it in your multimodule project’s level build.gradle file. By doing so, the code becomes more straightforward and easier to understand.

Here’s an example illustrating documentation versioning for the project. By employing the versioning plugin, we can display a dropdown menu containing different versions of our project. This enables users to access the documentation corresponding to their desired version effortlessly.

Conclusion

To wrap it up, Dokka and the Dokka Versioning plugin are invaluable assets for Kotlin projects. Dokka simplifies documentation creation, enabling developers to present their code effectively. Meanwhile, the Dokka Version plugin adds a convenient versioning feature, facilitating seamless navigation between different documentation versions.

By utilizing these tools together, developers can enhance project organization, collaboration, and overall project quality. Whether you’re a novice or an expert developer, integrating Dokka and the Dokka Version plugin into your workflow is a smart move for improved documentation and project management.