KT-21392 Fix the description of `MutableMap.getOrPut()`

[mnonnenmacher]

Make clear that the defaultValue is also called if the key is present in the map but the value is null.

See: KT-21392

If you like this change I can make another commit for getOrElse which has the same problem.

[sschuberth]

Wouldn't the more appropriate fix be to change the implementation to match the documentation? As I believe the documented behavior also is the behavior most developers would expect.

[mnonnenmacher]

@sschuberth: Yes, fixing the implementation would be my preferred fix, too, but I had doubts if it would be accepted as it is a potentially breaking change.

[sschuberth]

In this case, I wouldn't regard it as a breaking change (i.e. you're not changing docs & implementation to behave differently than before), but a bug fix to make the implementation match the documentation (and desired behavior).

[glasser]

This surprised me today! Good thing I usually read implementations and not just docs...

[tomyuval]

Any news about this? This has been open for over two years now! (Mind you, I personally agree that the documentation is correct and the implementation is buggy, so I'd much rather see the implementation fixed. But if the designers of Kotlin don't agree, then at the very least the documentation should reflect what the functions actually do!)

[sschuberth]

Can we please get this merged? This just fixes the docs to match the implementation, so it's not a breaking change.

While I'd personally prefer to actually change the implementation, that's certainly not going to happen any time soon. In any case, docs and implementation should stay aligned.

[sarahhaggarty]

As this has been fixed as part of another PR, I'm going to close this PR. Thanks for your input!