Image for post
Image for post

Analyzing Kotlin sources just got simpler

Marcin Aman
Nov 9 · 3 min read

Analyzing Kotlin code used to be hard and required extensive know-how, because most of the concepts required to make it work were internal and not documented. Not anymore.

Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java. It understands standard Javadoc comments in Java files and KDoc comments in Kotlin files, and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
Recently it has been rewritten to be more flexible and allow users to write custom plugins. Thanks to its pluggability, Dokka code is available as separate artifacts and can be added as project dependencies. The newest 1.4 release introducesdokka-analysis dependency that makes it easy to analyse Kotlin and Java code. Let’s learn how we can use it by setting up a simple project that will analyse the source code of klaxon, a JSON parser for Kotlin.

First, we need to add dependencies on the dokka-analysis and dokka-core artifacts to provide interfaces required for the job:

implementation("org.jetbrains.dokka:dokka-analysis:1.4.10.2")    implementation("org.jetbrains.dokka:dokka-core:1.4.10.2")

Second, we need to define what should be analysed by defining a source set:

After that we are almost set up — all we need is to create a KotlinAnalysis
instance and get the packages from the code:

Now that the hard work is over, let’s dive into how we can analyse Kotlin code. We got some objects representing packages called Descriptors. Kotlin uses them to represent its own code. They contain all the information about accessibility, documentation, declared elements etc., a broader explanation of this topic is better left for another discussion. For now, let’s keep to this simplified view.

We can extract the data from those directly, but I think it is a great opportunity to use a visitor pattern — by extending a basic visitor from the Kotlin compiler we can gather information about relevant pieces of code.

To show a basic example, let’s find the names of all classes in the source set and determine which one is the longest. Piece of cake!

This may look convoluted at first, but it can be very quickly understood. In this case, we visit a package first, then analyse a class to get its name and return all names in a list. Simple stuff.

After cloning the repo and running our program we get:

Longest class name: JsonParsingException, length: 20

Now let’s create something a little bit more advanced. Suppose that the API of some class has changed, and we would like to estimate how much work it would take to adjust our codebase to the new standard. To measure that, we need information about functions that take this class as a parameter. Of course, this won’t give us a whole picture, but for sake of simplicity of this article, it is sufficient.

Let’s go back to our previous code and check how we can extract information about the function’s parameters. First, let’s create a handler for function descriptors as we definitely will need them:

Then we should analyse what this descriptor contains. We can see that it holds its parameters list in valueParameterproperty, bingo!

Ok, but how can we get information about functions? To do that, we need to look into places where they can be stored. In Kotlin functions can be declared on package level or class level. For each place we need to check what is declared there using getContributedDescriptors and filter for functions:

It might be useful to fetch the information about constructors as well, as they practically are functions:

Usages as a parameter for: kotlin.reflect.KClass: 
TypeFor/<init>
Annotations/Companion/findJsonAnnotation
Annotations/Companion/findProperties
Annotations/Companion/findNonIgnoredProperties
Annotations/Companion/findJsonPaths
Annotations/Companion/findJsonPaths
Annotations/Companion/isList
Annotations/Companion/retrieveJsonFieldName
JsonObjectConverter/fromJson
JsonObjectConverter/initIntoUserClass
JsonObjectConverter/retrieveKeyValues
JsonObjectConverter/calculatePolymorphicClass
JsonObjectConverter/PolymorphicInfo/<init>
Klaxon/parser
Klaxon/fieldConverter
Klaxon/fromJsonObject
Reflection/Companion/isAssignableFromAny

The project used in this article is available on Github.

With the latest Dokka release users have received not only a significantly better documentation tool, but also an easy way to have fun playing with source code analysis. I hope that in the foreseeable future more and more tools will be built on those foundations to make writing in Kotlin even more enjoyable experience.

VirtusLab

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store