Documentation with KDoc for Kotlin/Android
Think about you’re creating a library and you want to publish it on Git, or even you’re writing your casual code on some project, you need to write good documentation for other people too. what happens if someone wants to use your library or work beside you on an old project?
Here is KDoc, a language for writing documents for Kotlin code !!!
Similar to JavaDoc you the main format for KDoc is :
starting with /** and end with */.
In KDoc we can use tags, a tag formula is @tagname+ space +name (or sometimes just @tagname ), here is an example :
On the code above you can see :
- first I write a summary about the foo function
- adding @param input so other programmers can understand what is input
Let’s see some famous tags :
@param => you can document a parameter of a function or generic type of a class or … :
as you can see we can use T or [T] (when you use [T] you can don’t use space after @param.
@propertity => document properties of constructor
@return => document what is the output of a function
@constructor => document what is the primary constructor
@throw + class => document what kind of exception will throw when something goes wrong
@see => add a link or method as a reference
@sample => show an example of code
you can find more tags on Kotlin website.
here is a good example :
It’s nice, right? remember the documentation should not be so long, just a summary of what is happening in this class would be enough.
Let’s move forward to the next step, using Dokka!
Dokka is a documentation engine for Kotlin, It can create better visual documentation for us.
Look at this picture:
Ok let’s see how we should create this, first we need to add these to Gradle:
after this enter this on terminal: gradlew.bat dokkaHtml (I believe ./gradlew for Linux/Mac) and after building you can find that on app\build\dokka.
Instead of dokkaHtml you can try dokkaGfm and dokkaJavadoc.
contact me: shobeyri.ali@gmail.com
my Linkedin : https://www.linkedin.com/in/iryebohs/
