godotengine / godotengine/godot-docs
Explain return value of methods in packed arrays
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:** v4.5.1.stable.flathub [f62fdbde1]
**Issue description:**
Methods in packed arrays lack explanation about their return values. The docs act as if methods that return bool have an obvious meaning, but it's far from it. If you don't explain it, I can't know if I'm supposed to expect true of false on success, and when it could fail.
For example, strangely, `append_array` and `Array.append` are void, but `Packed*Array.append` are bool, without any explanation. If I just ignore it, I get `RETURN_VALUE_DISCARDED` warning, so I'm supposed to check it for failure. It's like one of those methods that return int but should really return Error (like Signal.connect and Array.insert) except worse because there's no acknowledgement of the return value whatsoever, and [I even read somewhere that it seems to be the opposite of what one might expect](https://www.reddit.com/r/godot/comments/17hr1uu/comment/k6pbni1/) (true on failure?).
The return explanation seems to be lacking in all `Packed*Array` methods for, at least:
- `append(...)` -- no acknowledgement of return value whatsoever
- `push_back(...)` -- same as above; true on failure or success? when can it fail, and can I do anything about it (will it crash)?
- `insert(...)` -- `Array.insert` has an explanation, but I can't just assume it's the same on packed arrays unless docs say so
- `PackedByteArray.encode_var(...)` -- the only `encode_*` method that returns a value, without explaining what it is
**URL to the documentation page:**
- https://docs.godotengine.org/en/stable/classes/class_packedbytearray.html
- https://docs.godotengine.org/en/stable/classes/class_packedcolorarray.html
- https://docs.godotengine.org/en/stable/classes/class_packedfloat32array.html
- https://docs.godotengine.org/en/stable/classes/class_packedfloat64array.html
- https://docs.godotengine.org/en/stable/classes/class_packedint32array.html
- https://docs.godotengine.org/en/stable/classes/class_packedint64array.html
- https://docs.godotengine.org/en/stable/classes/class_packedstringarray.html
- https://docs.godotengine.org/en/stable/classes/class_packedvector2array.html
- https://docs.godotengine.org/en/stable/classes/class_packedvector3array.html
- https://docs.godotengine.org/en/stable/classes/class_packedvector4array.html
---
Also, is it possible to change the API of methods returning `int` to `Error` and consider it a non-breaking improvement in GDScript/Core? Because I get no errors or warnings when I assign a method returning `Error` to an int variable (only the opposite raises a warning, since the enum is more specific), so this shouldn't break existing code, right? At least in GDScript?
For example, in:
- `insert`, `Array.insert`
- `resize`, `Array.resize`
- `Signal.connect`
- etc...
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.