Hey guys, I am slowly introducing Kotlin to a larger codebase. In our existing Javadoc, we use HTML...

# dokka

[Christoph Loy]

Hey guys,

I am slowly introducing Kotlin to a larger codebase. In our existing Javadoc, we use HTML divs with different classes to e.g. specify which part of the doc is public and which is not. We then have a toolchain that parses these tags and extracts documentation.

Now in Kotlin, this seems to no longer be possible since HTML tags get swalled by the IntelliJ popup. Do you have any good alternatives for KDoc so that I can mark parts of the documentation? I need this to work inline.

Thanks in advance!
Christoph

[CLOVIS]

You could create a private section and modify your script to search using that except of a div?

/**
 * Common description
 *
 * ### Public
 * 
 * Public additional information
 *
 * ### Private
 *
 * Private additional information
 */

[CLOVIS]

I'm curious what private information you are documenting this way, however

[Christoph Loy]

Yeah that would work. But then the public and private headline would appear in the regular doc. Sure, no dealbreaker but still a degratation compared to our previous solution.

[Christoph Loy]

Since you were curious: The "public" information is extracted in a PDF while the "private" docu stays in KDoc/Javadoc. So in the end, both parts are accessible. Just
wanted to simplify my problem a bit 🙂

[CLOVIS]

So, in IDEA, you want to see everything, and you want a marker to specify what should not be exported by your custom tooling when generating a PDF?

[Christoph Loy]

I want to see everything in IDEA but want a marker what SHOULD be exported in a PDF 🙂

[CLOVIS]

What about:

/**
 * Test
 *
 * <private>Only visible in IDEA</private>
 */

[CLOVIS]

When generating your PDF, you can just remove all <private> tags?

[Christoph Loy]

Yeah sounds good 🙂 But this only works when the doc does not start with the private tag.

[Christoph Loy]

grafik.png

[Adam S]

KDoc uses Markdown, and Markdown should allow for embedding HTML. But I don’t know how well IJ respects them, or copes with styling. \Do you have an example of what classes/tags are ‘swallowed’?

[CLOVIS]

You have to leave an empty line:

[Christoph Loy]

@Adam S It seems to always swallow the first HTML tag if its the first character of the doc. No matter what its named or whether it has attributes. I tried the names "private", "div" and "ext-doc".

[CLOVIS]

https://stackoverflow.com/a/29378250

[Christoph Loy]

@CLOVIS Interesting...though both of these cases look like weird hacks to be honest. Wil be rough to communicate this to my colleagues.

[Christoph Loy]

I am wondering though: Could it be that the behaviour we are observing is a bug in IDEA? More specifically, that it should be allowed for KDoc to start with HTML but IntelliJ does have an issue with that? Because in the HTML doc generated by dokka, starting with an HTML tag works just fine.

[Adam S]

I suspect (but have no evidence) that IntelliJ and Kotlin will be using https://github.com/JetBrains/markdown to parse the Markdown. It’s not a very user-friendly library, the docs are quite sparse, but maybe there’s something that would help.

[Christoph Loy]

Hmm I'll look into that

[Adam S]

the Markdown spec has several slightly different implementations. It’s possible that Dokka is using a different flavour to IntelliJ, which might have an impact in this way.

[Christoph Loy]

Yeah sure. But in an ideal world, Dokka and IntelliJ should have the same interpretation of markdown, right? Just asking because I am wondering whether I should open a Bug for IDEA or not.

[Adam S]

this is what IJ shows

https://kotlinlang.slack.com/files/U052WJUFHM2/F052DTAA86T/grafik.png▾

What does Dokka show for the same code?

[Christoph Loy]

@Adam S I had a look at the Jetbrains/markdown repo and it says that the lib is used by the IDEA Markdown plugin. Therefore I tried to create a md file that starts with HTML in IDEA and that worked just fine...So thats a hint that the issue is not in this library, imo.

[Christoph Loy]

@Adam S In dokka HTML, it works just fine.

[Adam S]

yeah, make an issue on YouTrack. Either way, it’s unexpected behaviour, right?

[Christoph Loy]

Yeah thats also my intuition 🙂 Would you agree that this is more a bug in IDEA and not a bug in Dokka?

[Adam S]

you could argue it either way 🤷‍♀️. I wouldn’t worry about which team it’s assigned to, the ticket can always be moved

[Christoph Loy]

Just as an update: This behaviour was already reported here: https://youtrack.jetbrains.com/issue/KT-54538/IntelliJ-IDEA-Ctrl-Q-popup-skips-contents-[…]-completely-if-they-are-used-in-KDoc-in-some-Kotlin-files