`RandomNumberGenerator` - `randi_range` and `randf_range` can swap endpoints

[elowynd-id]

Your Godot version:
4.5.1

Issue description:
The document for the RandomNumberGenerator class is missing some pieces of information regarding what happens when float randf_range(from: float, to: float) and int randi_range(from: int, to: int) are called with from > to.
For randi_range, the documentation of the GobalScope functions explains that the parameters are swapped when such a situation occurs. It seems to be the same for methods from the class RandomNumberGenerator, but the documentation does not mention it.
It is not necessarily an obvious behavior. One could, for instance, expect and exception. So I think the documentation of these two methods should mention this behavior.

URL to the documentation page (if already existing):
https://docs.godotengine.org/en/latest/classes/class_randomnumbergenerator.html

[AThousandShips]

The arguments being swapped is not true for randf_range, only for randi_range, for randf_range the same is essentially true as it does randd() * (p_to - p_from) + p_from

[elowynd-id]

The arguments being swapped is not true for randf_range, only for randi_range, for randf_range the same is essentially true as it does randd() * (p_to - p_from) + p_from

Good to know. I must confess that I did not check what happens in detail. I just quickly saw that the documentation for the global scope randi_range mentioned swapping arguments, and I guessed randf_range would have a similar behavior.

Your answer show that the title of the issue might be a bit incorrect, but the idea remains the same: from the documentation of the methods alone, I find it not clear what behavior should be expected. Other languages/libraries make different choices, and the documentation is not precise enough. Sure, users should sanitize their arguments if they expect any other behavior, but it would still be nice to have it precised in the documentation.

[AThousandShips]

At minimum the description of the random number generator should probably match, as it simply called by the global scope method

For the floating point case we can add a note that the order doesn't matter, but that's not necessarily intended, it's possibly just the unintended consequence of the mathematics involved, so I'd say we shouldn't add it unless we know it's an intentional feature and not just an implementation detail

[elowynd-id]

At minimum the description of the random number generator should probably match, as it simply called by the global scope method

Yep, that's what I thought.

For the floating point case we can add a note that the order doesn't matter, but that's not necessarily intended, it's possibly just the unintended consequence of the mathematics involved, so I'd say we shouldn't add it unless we know it's an intentional feature and not just an implementation detail

Whether it is an intentional feature or not, it is the current behavior. Shouldn't the documentation explain the behavior of current implementations?
Additionally, it is most likely a behavior used as an actual feature by users. So changing the mathematical implementation would break code. Therefore, this is probably a change that would not happen, or only during a jump to a new major version. And in this case, we could expect such change to trigger an update of the documentation.

I am not a contributor, so I might miss something and perhaps my point of view is not exactly aligned with how things are done.

[AThousandShips]

Shouldn't the documentation explain the behavior of current implementations?

No not if it's not intentional, only intentional features and details should be documented, if people rely on something that's not documented they do that at their own risk, it's not breaking compatibiltiy to change that if it's not expected or reasonable to swap the arguments for example, unless it's documented. So if someone discovers something undocumented that isn't reasonable to expect to be a thing (like swapping the arguments of a method) and they depend on it that's unfortunately at their own risk and we can't limit what changes we can make based on that

So we should only document what we decide is intentionally part of the feature, and not implementation details or unintended consequences of the implementation

I hope that clears that up

[elowynd-id]

Ok. So the documentation is also a form of specification. Makes sense, thanks for the explanation.

In that case, I think it would also make sense to decide whether this is supposed to be a feature or not. Especially since the current behavior is almost the same as the intentional feature of swapping arguments for the integer version currently (documented for the global scope). But I guess this is something that should not be discussed here but on the engine side instead.

[AThousandShips]

I don't think it's necessary to mention it on the floating point part, I don't think anyone should need to use it, or should really use it, I'm not even sure why the swap even is in the integer version it's sort of odd and goes against the naming of the arguments, but we can't change it now