Clarify documentation for 'list.group'

[voneiden]

Reworded the summary line to use similar structure as other function summaries in the list module and made the note about not preserving initial value order be more specific.

While in hindsight it makes sense what "does not preserve" means, and it can also be deducted from the supplied examples, at least for me it wasn't obvious at first glance and I ended up looking at the source code for answers.

[lpil]

Remove the guarantee that it is reversed please.

[voneiden]

Sure, "may be reversed" alright? Is the reasoning behind this that strictly speaking reversing only happens (as a side effect) when group size > 1 or am I missing something?

[lpil]

Please remove the comment on it being reversed. The previous documentation was accurate.

[voneiden]

Sorry for being obtuse, but I feel like there's still some misunderstanding on either end. Allow me to try to elaborate

Remove the guarantee that it is reversed please.

group does a left fold and prepends each element on a sublist. I am confused; under what circumstances does this not result in a guaranteed reversed order in the sublists?

The previous documentation was accurate.

Right, but isn't it also rather ambiguous? Without prior knowledge of the implementation details, "Does not preserve the initial value order." can be interpreted to mean that the order is reversed, random or anything else in between.

[GearsDatapacks]

I think the idea is that changing the implementation in the future would not be a breaking change. The order is not guaranteed. Right now it's reversed, but you should not rely on that in any way as is not part of the API.

[lpil]

@voneiden You are attempting to change the contract that we the Gleam maintainers have with the users of this code. Any such changes cannot be made via a pull request with no prior discussion.

[voneiden]

Aha, I see now, thanks. "Not guaranteed" would have been much better wording than "not preserved", although I doubt the former interpretation was the intent of the author. Even @lpil suggested in the implementing PR that users can reverse the lists themselves if they need the values in original order.

Considering that, changing the ordering in the future without it being considered a breaking change would seem rather dangerous to me. Yes, there's a contract and you can certainly appeal to it, but as can be seen, I failed to understand it correctly. Perhaps I'm the first, but I doubt I will be the last.

Would it be best to close this PR and I proceed by creating an issue for further discussion?