[SPARK-48842][DOCS] Document non-determinism of max_by and min_by

[zhengruifeng]

What changes were proposed in this pull request?

Document non-determinism of max_by and min_by

Why are the changes needed?

I have been confused by this non-determinism twice, it occurred like a correctness bug to me.
So I think we need to document it

Does this PR introduce any user-facing change?

doc change only

How was this patch tested?

ci

Was this patch authored or co-authored using generative AI tooling?

no

[JoshRosen]

+1 towards improving the documentation here.

I think the non-determinism might be clear to anyone who is already familiar with the non-determinism of first, last, etc., but it doesn't hurt to call it out explicitly.

I see that we have made similar documentation improvements in the past, e.g. in #27099. In that PR, it looks like we updated multiple documentation sources, including Python, R (where applicable), the Scala docs for the expression itself (which also feed into the SQL function catalog documentation), the functions.scala docs, etc. Maybe we should also update those other sources as part of this PR? Due to Spark Connect, it looks like we might now have two copies of functions.scala that might need updates.

Those existing docs have fewer examples than the PySpark docs, so in that setting it's probably fine to just add the one-sentence note about non-determinism.

[zhengruifeng]

+1 towards improving the documentation here.

I think the non-determinism might be clear to anyone who is already familiar with the non-determinism of first, last, etc., but it doesn't hurt to call it out explicitly.

I see that we have made similar documentation improvements in the past, e.g. in #27099. In that PR, it looks like we updated multiple documentation sources, including Python, R (where applicable), the Scala docs for the expression itself (which also feed into the SQL function catalog documentation), the functions.scala docs, etc. Maybe we should also update those other sources as part of this PR? Due to Spark Connect, it looks like we might now have two copies of functions.scala that might need updates.

Those existing docs have fewer examples than the PySpark docs, so in that setting it's probably fine to just add the one-sentence note about non-determinism.

make sense, let me only add a note and also update other documents

[allisonwang-db]

I think this is a bit hard to understand. Is there a simpler example we can use to demonstrate this idea?

[HyukjinKwon]

I think we can just say that The function is non-deterministic so the output order can be different for those associated the same values of `col`

[zhengruifeng]

thanks all, merged to master