Skip to main content

Generate Kotlin Docs using Dokka


Have you ever generated Kotlin docs (Kdocs) for your library/project? I have. There is a tool for this called Dokka and you can find it here. It's not too hard to set up.

I personally used Dokka for a small API i wrote for SharedPreferences. Anyways, the steps are pretty basic. One thing you must be careful though, is to know the syntax of the Kdocs pretty well (usually, if you know how to generate Javadoc, Kotlin docs don't have much difference).

Let's take a simple example:

/** Reads a String from SharedPreferences
* @param [key] the key provided to find the stored value
* @return [String] the data of type String if found if not returns an empty String
* @throws [java.lang.ClassCastException] if the key is found but is not a String
*/
@Throws(java.lang.ClassCastException::class)
fun readString(key: String, defaultStringValue: String = ""): String =
sharedPreferences.getString(key, defaultStringValue)
?: throw java.lang.ClassCastException("The key exists, but its' value not of type String")

All the commented lines will generate later what we call, the Kotlin Docs/Kdocs (or you can yell at people: "Read the bloody docs" 🤣). Being careful to describe exactly what the function does and check all his components, parameters, return values, exceptions, is the key to generating clear documentation for your project.

So, let's set up Dokka first.

Go to build.gradle (project level) and add this line:

classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.18" //or later version

Than, just apply the plugin in the build.gradle (level module):

apply plugin: 'org.jetbrains.dokka'
...
android {
   ...

    dokka {
        outputFormat = 'html'

        outputDirectory = "$buildDir/javadoc"
    }
}

All is now set up. As you may have notice the format will be html. Feel free to check the docs for other formats (never used any other).

So, let's suppose you have written some comments with the purpose of generating the documentation. After that, just type:

./gradlew dokka

Wait for some seconds and there you would see some success message, or if you have done something wrong, the CLI will notify you.

If you have successfully generated the docs, you will find the files on the build folder. After that, it's up to you in where to host them (I use github pages). The CSS of the docs are pretty nice and simple. But you can modify that if you want.

Here is an example you can see about Kotlin docs.

Stavro Xhardha

Popular posts from this blog

Modularizing your Android app, breaking the monolith (Part 1)

Inspired by a Martin Fowlers post about Micro Frontends, I decided to break my monolithic app into a modular app. I tried to read a little more about breaking monolithic apps in Android, and as far as I got, I felt confident to share my experience with you. This will be some series of blog posts where we actually try to break a simple app into a modularized Android app.

Note: You should know that I am no expert in this, so if there are false statements or mistakes please feel free to criticize, for the sake of a better development. 

What do you benefit from this approach:
Well, people are moving pretty fast nowadays and delivery is required faster and faster. So, in order to achieve this, modularising Android apps is really necessary.You can share features across different apps. Independent teams and less problems per each.Conditional features update.Quicker debugging and fixing.A feature delay doesn't delay the whole app. As per writing tests, there is not too much difference about…

What I learned from Kotlin Flow API

I used to check the docs and just read a lot about flows but didn't implement anything until yesterday. However, the API tasted really cool (even though some operations are still in Experimental state).Prerequisites: If you don't know RxJava it's fine. But a RxJava recognizer would read this faster.Cold vs Hot streamsWell, I really struggled with this concept because it is a little bit tricky. The main difference between cold and hot happened to be pretty simple: Hot streams produce when you don't care while in cold streams, if you don't collect() (or RxJava-s equivalent subscribe()) the stream won't be activated at all. So, Flows are what we call cold streams. Removing the subscriber will not produce data at all, making the Flows one of the most sophisticated asynchronous stream API ever (in the JVM world). I tried to make a illustration of hot and cold streams: Since I mentioned the word asynchronous this implies that they do support coroutines also. Flows vs…

From Gson to Moshi, what I learned

There is no doubt that people are getting away from GSON and I agree with those reasons too. The only advantage GSON has over other parsing libraries is that it takes a really short amount of time to set up. Furthermore, the most important thing is that Moshi is embracing Kotlin support.

First let's implement the dependency:
implementation("com.squareup.moshi:moshi:1.8.0") It's not a struggle to migrate to Moshi. It's really Gson look-a-like. The only thing to do is annotate the object with @field:Json instead of @SerializedName (which is Gsons way for JS representation):

data class User( //GSON way @SerializedName("name") val name: String, @SerializedName("user_name") val userName: String, @SerializedName("last_name") val lastName: String, @SerializedName("email") val email: String ) data class User( //Moshi way @field:Json(name = "name") val name: String, @field:Json(name = "user_name…