Date: 15 September, 2024

• Purpose of this document: To provide guidance on installing and using Dokka for generating documentation in Android projects.

• What is Dokka?: Dokka is a powerful documentation tool specifically designed for Kotlin and Java projects. It generates documentation from comments written in Javadoc or KDoc, making it particularly useful for developers working in Android Studio.

  In this guide, Dokka is evaluated as a potential tool for generating clear, structured documentation for the Smart Living Community project, focusing on its Java codebase.

  Example:

  In our Smart Living Community project, Dokka will help generate clear and readable documentation for Java code, making it easier to understand the structure and usage of various classes and methods.

• The goal of using Dokka in this project is to create organized, maintainable documentation that reflects the project's APIs and their use cases, fostering seamless collaboration among team members.

  Example:

  Dokka helps us automatically generate structured API documentation in the Smart Living Community project, making it easier for both new and existing team members to understand and collaborate on the project.

Before installing Dokka, ensure the following are available:

• Android Studio Koala | 2024.1.1
• Kotlin DSL (build.gradle.kts) as the build configuration.
• Successful project sync with Gradle files.

1. First, sync the Gradle files with the project by navigating to File -> Sync Project with Gradle Files.
   

   Figure 1.1: Open the project and sync with Gradle files

   
   

2. Add the Dokka dependency to the module-level build.gradle.kts file:

   plugins {
       id("org.jetbrains.dokka") version "1.9.20"
   }
   
   dependencies {
       dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:1.9.20")
   }

   See the screenshots below for better understanding:

   

   Figure 2.1: Add the annotated line inside plugins block

   

   Figure 2.2: Add the annotated line inside dependencies block

3. Sync the Gradle file by navigating to File -> Sync Project with Gradle Files to apply the changes.

4. Add a BlankFragment by navigating to File -> New -> Fragment -> Fragment (Blank), and select Kotlin as the source language, then click Finish.

   

   Figure 4.1: Adding Kotlin fragment for Dokka compatibility

   
   

   

   Figure 4.2: Selecting Kotlin as the fragment language

5. At the bottom-left corner of Android Studio, open Terminal. Type the following command in the terminal:

   ./gradlew dokkaHtml

   

   Figure 5.1: HTML documentation generation command

   

   Figure 5.2: HTML documentation successfully generated

6. You can find the generated HTML documentation in the directory shown in the screenshot below:

   

   Figure 6.1: Open index.html to view the documentation

7. After opening the index.html file, the documentation will appear as a webpage in your browser:

   

   Figure 7.1: The documentation file for the Smart Living Community project

To generate documentation in formats like Javadoc or Markdown, change the task to:

./gradlew dokkaJavadoc
./gradlew dokkaMarkdown

• Version Mismatch: Ensure the Kotlin JVM target version and the Java version are the same.
  

  Figure: Ensure JVM target and Java version match

Javadoc is a documentation tool provided by Oracle for generating API documentation in HTML format from Java source code. It uses special comments called "Javadoc comments" that are written in the source code and parsed to create user-friendly documentation.

Javadoc comments are written using /** ... */ notation. These comments precede the class, method, or field definitions that they describe. Some common tags used in Javadoc are:

• @author - Specifies the author of the code.
• @version - Specifies the version of the code.
• @param - Describes the parameters of a method.
• @return - Describes what a method returns.
• @throws - Lists the exceptions that a method can throw.

Example:

/**
 * This class represents a simple calculator.
 * 
 * @author Jubaer
 * @version 1.0
 */
public class Calculator {

    /**
     * Adds two integers.
     * 
     * @param a the first integer
     * @param b the second integer
     * @return the sum of a and b
     */
    public int add(int a, int b) {
        return a + b;
    }
}

• Supports multiple output formats (HTML, Javadoc, Markdown).
• Works with both Kotlin and Java.
• Easily integrates with Gradle and Android Studio.

• Primarily focused on Kotlin, so it might not work as smoothly with Java.
• Some customization options may require deeper configuration.

• Java and Kotlin Support: Unlike Javadoc, which is primarily designed for Java, Dokka supports both Java and Kotlin projects, making it more versatile.
• Multiple Formats: Dokka generates documentation in multiple formats (HTML, Markdown, Javadoc), while traditional Javadoc only generates HTML.
• Customizable Output: Dokka provides more customization options, allowing better control over what to include in the documentation and how it's presented.
• Seamless Integration: Dokka integrates smoothly with Gradle and Android Studio, making it more convenient for Android developers.

Using Dokka in our project ensures that we maintain clean, well-organized API documentation. This improves team collaboration and makes the project easier to maintain in the long run.

• https://github.com/Kotlin/dokka
• https://kotlinlang.org/docs/dokka-introduction.html
• https://plugins.gradle.org/plugin/org.jetbrains.dokka
• https://www.baeldung.com/kotlin/dokka-documentation-introduction
• https://medium.com/androiddevnotes/how-to-use-dokka-documentation-engine-for-android-gradle-to-generate-kdoc-or-javadoc-comments-2b5f177595ec