Including source code documentation in a library
I run my Kotlin projects with Maven with a pom.xml file. I have produced library jar files for other projects to use for quite a while. Now I want to include the documentation (class comments) for the library functions and classes to show them in the other project consuming that library. I have spend now 2 hours already to figure out how that works and feel totally lost. Various tries of adding additional maven plugins or putting in two different jar files etc., etc. hasn't be gotten me anywhere.
Could somebody give me the crucial hints? Much appreciated.
1) How to export the library project properly in the first place?
2) How to import it properly in the target project?
All this happens totally local on my machine, so I have the jar files sitting somewhere in some folder and want to pick them up in the other project.
Please sign in to leave a comment.
Hi there,
Thanks for reaching out!
The key thing to know, IntelliJ shows KDoc comments by reading a separate sources jar. Your regular jar only contains compiled classes. The comments are stripped out at compile time.
You need to produce and install both jars.
1. Add the maven-source-plugin to your library's pom.xml inside the plugins block. Then run "mvn clean install". You should now see two files in target/: my-library-1.0.0.jar and my-library-1.0.0-sources.jar.
2. Check that both jars landed in ~/.m2 by listing the directory for your library version. You should see both the main jar and a -sources.jar there.
3. No changes needed in the consuming project's pom.xml. A normal dependency declaration is enough. Maven picks up the sources jar automatically.
4. After reloading Maven in IntelliJ, if docs don't appear right away, open the Maven tool window and use Download | Download Sources. Then hover over any function from your library and the KDoc tooltip should show up.
One more thing: if you ever want to generate standalone HTML API docs for your library, look into Dokka (dokka-maven-plugin). Not needed for what you're doing now, but it's the Kotlin-native way to do it down the road. Let us know if you run into anything!