How to add a KDoc comment for the receiver of a Kotlin extension function (first parameter in Java, `this` in Kotlin)

Question

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.

"expression" is a parameter in the regular function version. When you make it an extension function, there is no parameter. Just as your definition shows, the parameter becomes the receiver...the object itself that you've extended. You call `checkArguments` directly on a Boolean with no parameters. — CryptoFool, Oct 13 '20 at 01:31
The IS NO first parameter. The receiver is `this`. That's the equivalent of the parameter in the standard function version you show, but the two are different things. They aren't two ways to write the same thing. They're different things. — CryptoFool, Oct 13 '20 at 01:32
The only other thing I can think to tell you is that the method looks like this in Java: `public static boolean checkArguments(Boolean receiver) { if (!receiver) { throw IllegalArgumentException() } }` - It's in a class with a name that depends on the file the function is in. - but you never see that, so you can't "comment it". — CryptoFool, Oct 13 '20 at 01:35
Let us [continue this discussion in chat](https://chat.stackoverflow.com/rooms/222934/discussion-between-steve-and-fredsuvn). — CryptoFool, Oct 13 '20 at 01:50
@Steve it is, in fact, possible to put a documentation comment on the receiver of an extension function. My answer describes how to do so. — Ryan M, Oct 14 '20 at 18:41

Ryan M · Accepted Answer · 2020-10-14T18:33:13.753

2

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)

edited Oct 14 '20 at 18:33

answered Oct 13 '20 at 04:06

Ryan M

18,333
31
67
74

Cool. However, wasn't the question if the funny name given to the parameter could be changed to "expression"? Can that be changed with something special in a comment? - I guess I was thinking that the OP had already exhausted standard documentation mechanisms, as he seemed to be intent on documenting a strange case. If this is enough to save him from having to write a second function, then great! – CryptoFool Oct 14 '20 at 22:43
@Steve Thanks for the reply - I can definitely see how you could get that from the original question phrasing, which wasn't really 100% clear on the matter. Based on the OP accepting the answer and their edit adding ["Reopen: see first answer is right."](https://stackoverflow.com/revisions/64327122/4) to the question (which I removed with an additional clarifying edit), I think this was, in fact, the question they wanted answered. I tried to find a duplicate before answering and was surprised not to find one. If there really isn't a duplicate, this seems like a good one to reopen. – Ryan M Oct 14 '20 at 22:57
I agree. I voted to reopen this. I still think that the question itself could be clearer as to what is desired. – CryptoFool Oct 14 '20 at 23:35
@Steve it is not a `strange case`, I just write codes by kotlin, and the codes will be used for both java and kotlin. And I want that java users and kotlin users have the same experience. Actually, `@receiver` is not enough, I really want a way(looks like `@receiver(expression)`) to rename `receiver`(`$this`) to `expression` – FredSuvn Oct 15 '20 at 13:15
1

@FredSuvn for that, you'd want [Changing kotlin extension function receiver JVM name](https://stackoverflow.com/q/47775870/208273), which unfortunately indicates that that is impossible. – Ryan M Oct 15 '20 at 13:56

How to add a KDoc comment for the receiver of a Kotlin extension function (first parameter in Java, `this` in Kotlin)

1 Answers1