fixup! Update KEEP on Explicit backing fields feature

Author: merfemor

Diff for: proposals/explicit-backing-fields.md

@@ -56,6 +56,7 @@ class SomeViewModel : ViewModel() {
   * [Java interoperability](#java-interoperability)
   * [Reflection](#reflection)
 * [Future enhancements](#future-enhancements)
+  * [Underscore operator in type parameters](#underscore-operator-in-type-parameters)
 
 <!--- END -->
 
@@ -64,6 +65,9 @@ class SomeViewModel : ViewModel() {
 This proposal caters to a variety of use-cases that are currently met via a
 [backing property pattern](https://kotlinlang.org/docs/properties.html#backing-properties).
 
+To better understand pattern usage and to help in decision-making,
+for each pattern occurrence statistics were collected based on open repositories on GitHub.
+
 ### Use cases targeted by the explicit backing field feature
 
 #### Expose read-only supertype
@@ -118,6 +122,23 @@ val city: StateFlow<String> = _city.asStateFlow()
 It is usually more desirable for the primary property to be stored, as in the code snippet above or [this example](https://github.com/wikimedia/apps-android-wikipedia/blob/604007f38e834667f037c475b05f362b92a5575c/app/src/main/java/org/wikipedia/talk/template/TalkTemplatesViewModel.kt#L26-L30).
 However, computed property pattern is also quite popular ([example](https://github.com/jellyfin/jellyfin-androidtv/blob/b46f1acc99fc848abb9ef896c9bb2941e9c6e3ff/playback/core/src/main/kotlin/PlayerState.kt#L75-L88)).
 
+##### Convenient type cast without spelling the full type
+
+Also, conversion method like `asStateFlow` is used when we want to cast backing property to supertype,
+but we don't want to explicitly spell the full type (which is also was [one of the reasons of introducing `asStateFlow`](https://github.com/Kotlin/kotlinx.coroutines/issues/1973#issuecomment-621660861)):
+
+```kotlin
+private val _item = MutableStateFlow(ExtremelyLongTypeName.DefaultValue)
+val item = _city.asStateFlow()
+// shorter than
+val item: StateFlow<ExtremelyLongTypeName> = _city
+// or
+val item = _city as StateFlow<ExtremelyLongTypeName>
+```
+
+Apart from rewriting it using explicit backing fields, this use case could be reduced to the simpler form of [previous use-case](#expose-read-only-supertype),
+if [underscore operator in type parameters](#underscore-operator-in-type-parameters) was supported.
+
 ##### Hide complex value storage logic
 
 Sometimes we want to provide a public API for getting the immediate value of a variable,
@@ -232,7 +253,8 @@ Visibility of property must be more permissive than explicit backing field visib
 ### Resolution
 
 Calls of properties with explicit backing field are resolved to
-- the backing field, if call is made from inside the class (within private scope),
+- the backing field, if property is accessed from the same scope it is declared in
+  (actually, follows `private` visibility rules as per [specification](https://kotlinlang.org/spec/declarations.html#declaration-visibility)),
 - getter, otherwise.
 
 ```kotlin
@@ -250,7 +272,8 @@ fun outside(vm: SomeViewModel) {
 } 
 ```
 
-There is no possibility to call a getter inside the class
+There is no possibility to call a getter instead of field 
+when the property is accessed from the same scope it is declared in 
 (might be reconsidered in [Future enhancements](#future-enhancements)).
 
 ### Accessors
@@ -292,6 +315,12 @@ immediately after the backing field is initialized and then returned every time
 
 If property with explicit backing field has initializer, it's prohibited to declare accessors.
 
+> This use case stands out a little from the rest, 
+since it implies the simultaneous existence of two different stored values for one property,
+which sounds dissonant with the current mental image of properties in Kotlin.
+However, this is a case where the desire for consistency gives way to the importance of supporting a popular pattern
+(see [Expose different object](#expose-different-object)).
+
 ### Accessing field inside accessors and initializers
 
 It's possible to access explicit backing field by calling `field` from inside accessors (like it works now for ordinary
@@ -334,6 +363,8 @@ Neither property with explicit backing field:
 * nor explicit backing field itself can be `lateinit` (added to [Future enhancements](#future-enhancements))
 * nor explicit backing field itself can be delegated (added to [Future enhancements](#future-enhancements))
 
+It is not prohibited for a top-level property to have an explicit backing field.
+
 ## Technical details
 
 ### Grammar changes
@@ -410,7 +441,7 @@ public final StateFlow<String> getCity() {
 ### Reflection
 
 Callable reference to property with explicit backing field has type `KProperty<V>` (or its subtypes) where `V`
-is type of property (not backing field) regardless of whether it is called inside class or not.
+is type of property (not backing field) regardless of wherever it is accessed from.
 
 On JVM backing field can be obtained using [`javaField` extension](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect.jvm/java-field.html).
 
@@ -423,11 +454,29 @@ We strive to keep the design simple and uncluttered, so at this point we put asi
 Of course, we may revise some decisions in the future based on community feedback.
 Here is a list of the most obvious future enhancements for the feature:
 
-1. Make it possible to access getter instead of explicit backing field when referenced within the scope of visibility of explicit backing field. This is not supported because usually there is no need for calling getter (see [Access backing property inside](#access-backing-property-inside)).
+1. Make it possible to access getter instead of explicit backing field when the property is accessed from the same scope the property is declared in. This is not supported because usually there is no need for calling getter (see [Access backing property inside](#access-backing-property-inside)).
 2. Support other visibilities of explicit backing field (`protected` or `internal`).
 3. Support delegation of explicit backing field or property.
 4. Support `lateinit` explicit backing field.
 5. Support combining mutable explicit backing field and non-mutable property. 
 Despite its popularity (see [`var` backing property](#var-backing-property)), this use case is not supported in this proposal, because it is impossible for one property to behave as mutable + nullable and
 at the same time non-mutable and non-nullable.
 6. Add API in Reflection to retrieve information about explicit backing field.
+
+### Underscore operator in type parameters
+
+It's proposed to make [underscore operator](https://kotlinlang.org/docs/generics.html#underscore-operator-for-type-arguments)
+more powerful and support it in type parameters.
+
+This is a separate language feature, yet worth mentioning here,
+as it can help rewrite properties with explicit backing field in a better way in some cases
+(see [Convenient type cast without spelling the full type](#convenient-type-cast-without-spelling-the-full-type)).
+
+```kotlin
+val item = field.asStateFlow() // if we don't need read-only wrapper...
+    field = MutableStateFlow(ExtremelyLongTypeName.Default)
+
+// ...we could rewrite it like that without losing conciseness
+val item: StateFlow<_> // inferred StateFlow<ExtremelyLongTypeName> 
+    field = MutableStateFlow(ExtremelyLongTypeName.Default)
+```