I'm very confused about a recent change in kotlin ...

# language-evolution

[andrzej]

I'm very confused about a recent change in kotlin docs about usage of also scope function: https://github.com/JetBrains/kotlin-web-site/pull/1676/commits/c9d8e8fdb32ccf54da5b11459231e555a33eb597. It was already challenging to use scope functions properly (i.e. to not over- or mis-use them), this change made it harder...

From previous clear usage advice of when to use also, now it is smth. like: "use also for a specific reason ("Use also for actions that need a reference rather to the object than to its properties and functions") unless there is this shadowing, all the usage guidance do not count, use it as apply.
While reading code I need to analyse if also is put there because it was shadowing this or if it followed intended usage.
Not to mention that all code bases that applied previous rule for years become messy after starting to apply new version of the rule...
If really this change was needed, why not simplify it and just say: use it as apply, whenever it is more proper than this.

[ilya.gorbunov]

Basically, "use 'also' as 'apply', whenever it is more proper than `this`" describes the essence of what we have tried to convey with this new wording, but then the request to clarify "when it is more proper" would inevitably come.
So we expanded it with the situations when it is.

[andrzej]

ok, I see, thank you for explanation. Then I have the following suggestions for docs improvement:
1. All examples of also on this page are about logging, it would be good to change that (I understand now there are many other valid cases, yet no single example of them)
2. Update section "Here is a short guide for choosing scope functions depending on the intended purpose:" and namely statements: "Object configuration: apply " and "Additional effects: also ", now it should probably be a mix of both.
3. Still for me the following sentence: "Use also for actions that need a reference rather to the object than to its properties and functions" is a hint that using also in similar scenario as apply is discouraged and I if I understood you correctly, it is actually completely fine. Example: a mapping function as extension method - you would normally use apply but to avoid this shadowing you can use also (about which I have now some doubts because the docs say: "object rather than its properties")