Improved LocalDateTime documentation

[holgerbrandl]

Improved reasoning for missing date-time arithmetics and added an example

[holgerbrandl]

I figured later that this is greatly documented in https://github.com/Kotlin/kotlinx-datetime#date--time-arithmetic but maybe extending the javadoc makes sense as well.

What I also tend to do in my projects is to bluntly cross reference the main documentation via hyperlinks from the java-doc to keep docs centralized while avoiding redundancy. For example https://github.com/holgerbrandl/kalasim/blob/master/src/main/kotlin/org/kalasim/Component.kt#L131. I still wonder about the best practice here.

[dkhalanskyjb]

What do you think about writing something like this instead?

* See the documentation [LocalDateTime.toInstant] for an explanation of problems with raw [LocalDateTime] values.

It's nice to have information discoverable, but I also think that it's better to write one good explanation and link to it from ten places instead of writing ten unrelated explanations.

Or maybe it would be better to write one good explanation in some place other than LocalDateTime.toInstant. Or maybe the explanation in LocalDateTime.toInstant is also not good enough. WDYT?

[holgerbrandl]

Currently the actual explanation sits at https://github.com/Kotlin/kotlinx-datetime#date--time-arithmetic, but definitely, keeping it at once place with proper references is better.

[dkhalanskyjb]

I know, I'm the one who wrote the explanation ff43dd6. I agree with the spirit of this PR though, it would be nice for such things to be discoverable through KDoc only. The only question is, where to put the explanation in a systematic manner.

[dkhalanskyjb]

Superseded by #367.