Document Kotlin code using Dokka and KDoc - Part 1

Document Kotlin code using Dokka and KDoc - Part 1

Every good product should consist of a user manual to make users which will help to ease in using the product. When the product becomes comfortable for using it creates a huge impact. This is the same for producing any software. For a developer, understanding code creates a huge impact on creating user-friendly and correct functionality applications. This blog's main area of focus is about documenting Kotlin code in Android Studio. So to get a clear picture I decided to split the article into two parts. Part 1 will cover a basic introduction about what is documentation, why should we document code, and what is Dokka and KDoc.

What is code documentation?

Code documentation is the description that helps to understand what each code does in the application. For instance, it helps to give a clear overview of what each variable does, what a particular function is in the project, whether it has a parameter or any return type, and what its impact is in the code like details are being documented well.

Why should we document code?

Imagine a situation if you got an opportunity to work on a large project which has millions of code. You have been assigned to solve a bug in the section. Even if you find the line of code where the error is throwing but it has been called 2 functions so when you get that function you get to see an interlinked variable so to tackle a single problem you have to go through many lines of code and some times even fail to solve it.

This is where good documentation helps. Code documentation is usually used to understand what variables, classes, objects, functions, etc.. are used in the application and what is its purpose and give information about does it have any parameters, receiver, or does it have external links.

If you get enough info about the code it is easy to work in code which eventually led to a decrease in the amount of time spent on solving and implementing a solution in the application.

But always there are two worst-case scenarios while documenting

Lazy documentation

Lazy documentation is the document with the least information provided. If a document is not giving you enough information about functionalities it is lazily formatted. Which is good for nothing, because it doesn’t bring any value to make you understand the code.

OverInfo Documentation

Some documentation gives information more than what it needs resulting in uncleared usage of code and makes confusion about the code. Spending a fruitful time reading out documentation is important to understand the proper usage of code but what if it takes double effort to understand the code? or information overloading creates too much difficulty in processing the code for a developer or even led to uncleared usage, this happens in over info documentation

Good documentation characteristics

• Should be understandable

• It should be accurate and up to date

• Simple and concise

• Proper formatting

• The document should always hit the target

• Should properly describe each functionality

• It should properly document its parameters, links, receivers if any

What are KDoc and Dokka?

In Java, Javadoc is used to document java code . Before Dokka, there is no proper tool to document Kotlin. Dokka is a documentation tool that is similar to Javadoc. The main difference between Javadoc and Dokka is that Dokka supports documentation of both Kotlin and Java. Dokka the documentation is made possible with KDoc.

KDoc

KDoc is the language used to document Kotlin code. To generate good documentation proper commenting is needed, to do this KDoc helps to commend using block tags and markdown. It is basically a plugin used in Android studio which helps to document. We can use KDoc by the following

• KDoc commenting started using / ** as the opening tag and ended using */ closing tag

• KDoc supports block tags and inline and HTML markdown to provide additional information about the elements which is embedded using @ symbol

Block tags

• @ receiver: document receiver extension

• @ param: documents properties of class or functions with name and description``

• @ see: documents link to a specified class or function

Inline Markdown

• # h1, ## h2, [], > etc.. tags are supported

HTML tags

• <img>, <table>, <b>, <i> etc.. tags can also be used

Read more about markdown guides to get familiar

Dokka

It is a tool used in to generate documentation. The generated documentation can be viewed basically in formats that include HTML, markup, and standard Javadoc. Dokka supports documentation of both java and Kotlin. It generates a Kotlin document if it is embedded using KDoc in the Kotlin file and generates Javadoc if commented using Javadoc comments.

This whole blog is about basic information about documentation. Hope you enjoyed it and helpful in your development journey. As I said in the opening line this blog post has 2 parts. Part 2 is all about the implementation of the Dokka in the Android Studio to develop documentation. That's all for today.

Have a nice day 👋👋👋👋