I'm noticing that properties with private or prote...

# dokka

[mkrussel]

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.

[Big Chungus]

Do you have a screenshot of that?

[Big Chungus]

I'm wondering what you mean by "look like public"

[Big Chungus]

var with private setter should just become a public val in dokka

[mkrussel]

@get:MainThread
    final override var isDisposed: Boolean = false
        private set

[Big Chungus]

Deffo a bug

[Ignat Beresnev]

Hi! Could you submit an issue on github? Should be relatively easy to fix, not sure how it hasn't been caught 🤔

[Ignat Beresnev]

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

[Big Chungus]

I vote for using var solely for public setters

[ilya.gorbunov]

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.

[Ignat Beresnev]

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

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

[ilya.gorbunov]

protected set should be shown as a part of var property signature

[ilya.gorbunov]

provided that the protected is included in documented visibilities

[Ignat Beresnev]

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.

[Ignat Beresnev]

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

[ilya.gorbunov]

in what sense?

[Ignat Beresnev]

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

[ilya.gorbunov]

I found that I had already created an issue about setters: https://github.com/Kotlin/dokka/issues/2723