英文:
How to add a KDoc comment for the receiver of a Kotlin extension function (first parameter in Java, `this` in Kotlin)
问题
这个问题的关键是如何为 Kotlin 扩展函数中的接收者参数添加 KDoc 文档注释。通常情况下，KDoc 文档注释中使用@param标签来为函数的参数添加说明。但是，对于扩展函数的接收者参数，它们的文档注释需要以不同的方式处理。
以下是如何为 Kotlin 扩展函数中的接收者参数添加 KDoc 文档注释的示例：
/**
* Check the receiver Boolean value.
*
* @throws IllegalArgumentException if the receiver is `false`.
*/
fun Boolean.checkArguments() {
if (!this) {
throw IllegalArgumentException()
}
}
在这个示例中，我们没有使用 @param 标签，而是在函数文档注释的描述部分中提供了关于接收者参数的说明。这是因为接收者参数不像普通函数参数那样使用 @param，而是在函数描述中进行说明。
希望这有助于解决你的问题。
英文:
Consider this non-extension function:
fun checkArguments(expression: Boolean) {
if (!expression) {
throw IllegalArgumentException()
}
}
When I use this function in kotlin and java, I can see its parameter name: expression.
I could also write this same functionality as an extension function:
fun Boolean.checkArguments() {
if (!this) {
throw IllegalArgumentException()
}
}
When I write it as an extension function in this manner, the parameter name of the Boolean that it is called on (the this variable within the function, AKA the receiver) shows up as $this$checkArguments. How can I add a KDoc documentation comment for this parameter? Using @param $this$checkArguments doesn't seem to document it.
答案1
得分: 2
你可以使用 @receiver 来记录扩展函数的接收者。这里是相关文档。
例如：
/**
* @receiver 至少四个字符长的字符串
*/
fun String.firstFour() = this.substring(0, 4)
英文:
You can use @receiver to document the receiver of the extension function. Here is the relevant documentation.
For example:
/**
* @receiver A String that is at least four characters long
*/
fun String.firstFour() = this.substring(0, 4)
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论