https://kotlinlang.org logo
Channels
Powered by
#dokka
Title
# dokka
m

mkrussel

02/02/2023, 8:43 PM
I'm noticing that properties with private or protected setters look like they have public setters in the documentation. This is with 1.7.20.
b

Big Chungus

02/02/2023, 10:34 PM
Do you have a screenshot of that?
I'm wondering what you mean by "look like public"
var with private setter should just become a public val in dokka
m

mkrussel

02/03/2023, 1:19 PM
Copy code
@get:MainThread
    final override var isDisposed: Boolean = false
        private set
b

Big Chungus

02/03/2023, 1:20 PM
Deffo a bug
i

Ignat Beresnev

02/04/2023, 1:04 PM
Hi! Could you submit an issue on github? Should be relatively easy to fix, not sure how it hasn't been caught 🤔
I think it should be a val if the setter is private, but with protected setters it's a bit more complicated, and it depends on how you look at it. From the outside, it's a val, but if the class is open/abstract and you as an API consumer can call the setter, it's a var. It's sort of an implementation detail, but it might be important for the API reference reader, it's unclear. Not sure what is to be done here
b

Big Chungus

02/04/2023, 1:20 PM
I vote for using var solely for public setters
👍 1
🚫 1
i

ilya.gorbunov

02/04/2023, 7:48 PM
It's sort of an implementation detail, but it might be important for the API reference reader,
It's important for those who are gonna inherit from this class. A protected setter is equally important as any other protected member.
i

Ignat Beresnev

02/04/2023, 8:38 PM
It's important for those who are gonna inherit from this class.
A protected setter is equally important as any other protected member.
For sure, I don't think anyone is denying that. With the current UI and layout of Dokka, it's impossible to satisfy two use cases: those who just use whatever classes they see, and those who want to inherit from them. One of the parties is going to be confused. If you see the signature from the screenshot below, you will go and try to change it from your code and find out that you cannot, because there's no way you can actually access the setter. 
Foo
doesn't even have to be sealed, you can have a protected setter in a final class. And Dokka doesn't document protected API by default, so should we even consider the protected setter in this case? Anyhow, you'll be displeased
Copy code
sealed class Foo {
    var prop: String = "prop"
        protected set
}

class Inheriting : Foo()
Similarly, if you're looking for a solution to change something in a framework you're using (like Spring in which there's a lot "configure through inheritance"), you'll see the 
val
and think that it's not mutable, and go look for another solution and waste time. But you actually could change it through inheritance if you knew. You'll also be displeased
👍 1
i

ilya.gorbunov

02/04/2023, 8:39 PM
protected set
should be shown as a part of 
var
property signature
provided that the protected is included in documented visibilities
i

Ignat Beresnev

02/04/2023, 9:03 PM
Yeah, I also thought of that, but there are still corner cases to be discussed and resolved
provided that the protected is included in documented visibilities
If only public signatures are documented, should it be a 
val
then, not a 
var
? One one hand, if the library author doesn't want you to see protected api, it should be a 
val
. On the other, Dokka will be lying in this case, maybe the library author is not against you inheriting and changing things. For the HTML format, there could be additional hover tooltips or some visual indicators to help with it though. Anyhow, the bug with private setters should definitely be fixed and I think it can be done quickly, but with protected/internal setters it'll most likely be in the backlog for some time and need additional research and discussion.
Same question for final/sealed classes. De facto the property is a 
var
with a protected setter, which will be documented if 
documentedVisibilities == public, protected
. De jure you cannot change it because you cannot inherit from this class, so this information is useless to you, but if we display 
val
- Dokka will be lying in a sense
i

ilya.gorbunov

02/04/2023, 9:08 PM
in what sense?
i

Ignat Beresnev

02/04/2023, 9:25 PM
It will be generating signatures which are not the same as in code, which can be confusing in certain scenarios For instance, in internal closed source libraries where you can go and introduce new types without altering existing ones, or if you want to contribute a new implementation of something to a public library and you're investigating what could be done, but these cases are most likely a minority. Or if there's an open class inheriting from a sealed class - I think you can extend from the open class and still call the setter defined in the sealed class
i

ilya.gorbunov

02/05/2023, 1:19 AM
I found that I had already created an issue about setters: https://github.com/Kotlin/dokka/issues/2723
👍 1
9 Views
Powered by