Tables in KDoc?

Question

We usually have changelog in our Java DTO's that consists of a table defined in Javadoc:

/**
 * Changelog:
 *
 * <table>
 *     <tr><th>Version</th><th>Description</th></tr>
 *     <tr>
 *         <td>2</td>
 *         <td>Added field 'something'</td>
 *     </tr>
 *     <tr>
 *         <td>3</td>
 *         <td>Added field 'somethingElse'</td>
 *     </tr>
 * </table>
 */
public class MyDTO {
 ...
}

This renders (in Intellij using Javadoc preview) nicely into something like this:

Now we want to do the same thing for our Kotlin data classes. Reading up on the docs of KDoc where it says:

For inline markup, KDoc uses the regular Markdown syntax, extended to support a shorthand syntax for linking to other elements in the code.

So I've tried to create a table using Markdown syntax:

/**
 * Changelog:
 *
 *| Version       | Description                 |
 *| ------------- | --------------------------  |
 *| 2             | Added field 'something'     |
 *| 3             | Added field 'somethingElse' |
 *
 */
data class MyKotlinDTO(..) { 
    ...
}

But this renders (again using Intellij preview):

Which doesn't look like a table.

I've also tried just using an HTML table but that doesn't work either.

Question

Does KDoc support tables and if so how do you create one?

Answer 1

Currently KDoc does not support tables - there are issues opened on Github and Youtrack

There is some kind of workaround - you can surround text with ``` (triple backticks) to keep indentations and formatting

Answer 2

The only workaround is to generate a table with Markdown Tables Generator. For example,

Then paste into your documentation,