KDoc是否支持表格？类比Java DTO的Javadoc表格实践

问题背景 #

你提到在Java DTO的Javadoc中会用HTML表格来定义变更日志，示例代码如下：

/**
 * 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 { ... }

这段内容在IntelliJ的Javadoc预览中能正常渲染，现在想知道KDoc是否支持这类表格。

答案 #

当然支持！KDoc（Kotlin的文档注释语法）本身就兼容HTML标签，所以你完全可以在KDoc中使用和Javadoc一样的HTML表格来编写变更日志。

举个Kotlin中的示例：

/**
 * Changelog:
 *
 * <table>
 * <tr><th>Version</th><th>Description</th></tr>
 * <tr>
 * <td>1.1</td>
 * <td>Added property `userName`</td>
 * </tr>
 * <tr>
 * <td>1.2</td>
 * <td>Added nullable property `phoneNumber`</td>
 * </tr>
 * </table>
 */
data class UserDTO(
    val id: Long,
    val userName: String,
    val phoneNumber: String?
)

在IntelliJ IDEA或者Android Studio中预览这段KDoc时，HTML表格会和Javadoc里的一样正常渲染，清晰展示版本变更信息。

另外补充一点：KDoc也支持Markdown语法，如果你更习惯Markdown的表格写法，也可以直接用Markdown表格，同样能被IDE正确渲染，比如：

/**
 * Changelog:
 *
 * | Version | Description |
 * |---------|-------------|
 * | 1.1     | Added property `userName` |
 * | 1.2     | Added nullable property `phoneNumber` |
 */

这种写法会更简洁，你可以根据自己的习惯选择HTML表格或者Markdown表格。

内容的提问来源于stack exchange，提问作者Johan