如何继承 KDoc 文档？

Posted 2023-04-14

【中文标题】如何继承 KDoc 文档？

【英文标题】：How do I inherit KDoc documentation?

【发布时间】：2016-06-17 00:54:44

【问题描述】：

在 Java 的 Javadoc 中，有一种方法可以使用 @inheritDoc tag 在子类中继承方法的文档。

有没有办法在 Kotlin 的 KDoc 中做同样的事情？

基本上，我想做的是：

abstract class Base 
    /**
     * Some KDoc documentation here.
     */
    abstract fun foo()


class Derived: Base() 
    /**
     * Here is all the documentation from Base#foo's KDoc inherited.
     *
     * And here goes something more in addition.
     */
    override fun foo()  /* ... */ 

【问题讨论】：

@inheritDoc 不起作用吗？你试过了吗？

@CaseyB，是的，我做到了，IntelliJ 和 dokka 都不理解，他们只是将其显示为文本。

我找不到任何记录我的发现的内容，但据我所知，如果在覆盖上未指定任何文档，则 Kotlin Doc 在覆盖函数时会继承文档。现在我想知道的是如何“扩展”/“包含”基本文档......

@mfulton26，好的，现在我看到 dokka 默认插入父文档。如果您能找到自定义它们的方法，那就太好了，但对我来说，仅继承它们就足够了。

@hotkey 我确实查看了github.com/Kotlin/dokka，但没有发现任何有用的东西。您可以创建 GitHub 问题或 Kotlin YouTrack 问题来查询此类问题。

【参考方案1】：

如果继承的成员没有自己的文档，Dokka 总是将文档从基础成员复制到继承的成员。无法将基本成员文档与继承成员中提供的附加文本结合起来。

（Dokka 不支持 @inheritdoc Javadoc 标签，因为这不可避免地会导致只包含 /** @inheritdoc */ 的 cmets 激增，我觉得这非常无用和多余。）

【讨论】：

然而，由于某种原因，当我在没有文档的继承函数上点击 Ctrl + Q 时，它没有显示任何内容，但是基本函数确实指定了它，当我 Ctrl + B 到它时在基本函数上点击Ctrl + Q，将显示文档。也许这是一些 ide-plugin 错误。

@yole 当我在 java 类/接口的覆盖方法上点击快速文档快捷方式时，我看不到任何文档，而基类/接口有一些文档。这真的很不方便。是否有未解决的问题？

@LouisCAD 好像有。见youtrack.jetbrains.com/issue/KT-25035