godotengine / godotengine/godot-docs
Clarify rounding for `snapped*` functions
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
## Your Godot version:
4.7
## Issue description (describe via experience):
I look at `round`:
> Rounds x to the nearest whole number, with halfway cases rounded away from 0.
- `roundf(-0.5) # -1.0` yep, further from zero.
- `roundf(0.5) # 1.0` further from zero, all good here.
Then I look at `snapped` and its derivatives:
> Returns the multiple of step that is the closest to x. This can also be used to [**ROUND**] a floating-point number to an arbitrary number of decimals.
There's no mention of how it rounds a number, but it used the word "round" so I figure behaviour matches `round` a.k.a. "away from zero".
- `snappedf(0.5, 1.0) # 1.0` yep, further from zero.
- `snappedf(-0.5, 1.0) # 0.0` oh?
- `snappedf(-0.5, -1.0) # -1.0` it's based on the step, maybe?
Looking at the implementation, I see how this occurs (even if I don't know the reasoning behind the implementation).
```cpp
double Math::snapped(double p_value, double p_step) {
if (p_step != 0) {
p_value = Math::floor(p_value / p_step + 0.5) * p_step;
}
return p_value;
}
```
So I've pieced it together, but it required digging into the C++ which shouldn't be a requirement.
### Solution
Document that halfway cases are rounded up for a positive `step` and down for a negative `step`
## URL to the documentation page (if already existing):
https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-method-snapped
### Related Code:
[implementation: math_funcs.cpp](
https://github.com/godotengine/godot/blob/d7c45b19ccf6ddadc73d1c8423cd2848f59de437/core/math/math_funcs.cpp#L121-L126)
[docs: GlobalScope.xml](https://github.com/godotengine/godot/blob/d7c45b19ccf6ddadc73d1c8423cd2848f59de437/doc/classes/%40GlobalScope.xml#L1272-L1314)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with doc/classes/@GlobalScope.xml and review the snapped and related snapped* entries linked in the issue. Clarify the documented halfway-case behavior for positive and negative steps, then verify the generated GlobalScope documentation renders the updated wording.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100