如何为 Kotlin 扩展函数的接收者添加 KDoc 注释（Java 中的第一个参数，Kotlin 中的 `this`）答案

【问题标题】：How to add a KDoc comment for the receiver of a Kotlin extension function (first parameter in Java, `this` in Kotlin)如何为 Kotlin 扩展函数的接收者添加 KDoc 注释（Java 中的第一个参数，Kotlin 中的 `this`）
【发布时间】：2020-10-13 01:10:42
【问题描述】：

考虑这个非扩展函数：

fun checkArguments(expression: Boolean) {
    if (!expression) {
        throw IllegalArgumentException()
    }
}

当我在kotlin和java中使用这个函数时，可以看到它的参数名：expression。

我也可以编写与扩展函数相同的功能：

fun Boolean.checkArguments() {
    if (!this) {
        throw IllegalArgumentException()
    }
}

当我以这种方式将其编写为扩展函数时，调用它的布尔值的参数名称（函数中的 this 变量，也称为接收器）显示为 $this$checkArguments。如何为此参数添加 KDoc 文档注释？使用@param $this$checkArguments 似乎没有记录。

【问题讨论】：

“表达式”是正则函数版本中的参数。当你使它成为一个扩展函数时，没有参数。正如您的定义所示，参数成为接收器......您扩展的对象本身。您直接在没有参数的布尔值上调用 checkArguments。
IS NO 第一个参数。接收者是this。这相当于您显示的标准函数版本中的参数，但两者是不同的东西。它们不是写同一件事的两种方式。它们是不同的东西。
我想告诉你的唯一另一件事是，该方法在 Java 中看起来像这样：public static boolean checkArguments(Boolean receiver) { if (!receiver) { throw IllegalArgumentException() } } - 它位于一个类中，其名称取决于函数所在的文件。 -但你从来没有看到过，所以你不能“评论它”。
让我们continue this discussion in chat.
@Steve 实际上，可以在扩展函数的接收者上添加文档注释。我的回答描述了如何做到这一点。

标签： java kotlin extension-methods kdoc

【解决方案1】：

您可以使用@receiver 记录扩展函数的接收者。这是relevant documentation。

例如：

/**
 * @receiver A String that is at least four characters long
 */
fun String.firstFour() = this.substring(0, 4)

【讨论】：

酷。但是，是否可以将赋予参数的有趣名称更改为“表达式”不是问题吗？可以通过评论中的特殊内容进行更改吗？ - 我想我认为 OP 已经用尽了标准文档机制，因为他似乎打算记录一个奇怪的案例。如果这足以让他不必编写第二个函数，那就太好了！
@Steve 感谢您的回复-我绝对可以从原始问题的措辞中看出您是如何理解的，这并不是 100% 明确的。基于 OP 接受答案和他们的编辑添加 "Reopen: see first answer is right." 到问题（我删除了一个额外的澄清编辑），我认为这实际上是他们想要回答的问题。我试图在回答之前找到一个重复的，但很惊讶没有找到。如果真的没有重复，这似乎是一个很好的重新打开。
我同意。我投票决定重新开放这个。我仍然认为问题本身可以更清楚地说明想要什么。
@Steve 不是strange case，我只是用 kotlin 编写代码，这些代码将用于 java 和 kotlin。我希望 java 用户和 kotlin 用户有相同的体验。实际上，@receiver 是不够的，我真的想要一种方法（看起来像 @receiver(expression)）将 receiver($this) 重命名为 expression
@FredSuvn 为此，您需要Changing kotlin extension function receiver JVM name，不幸的是这表明这是不可能的。