Explain return value of methods in packed arrays

[geekley]

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 (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...

[Calinou]

Also, is it possible to change the API of methods returning int to Error and consider it a non-breaking improvement in GDScript/Core?

This breaks GDExtension compatibility, so no. GDScript compatibility is technically not broken by a change like this, but new warnings would be emitted in projects that enable the unsafe cast warning.

[geekley]

GDScript compatibility is technically not broken by a change like this, but new warnings would be emitted in projects that enable the unsafe cast warning.

Are you sure? I'm pretty sure I had all optional warnings enabled in the project when I tested that, and got none, not even a type unsafe line, unless it's some new warning introduced in 4.5. But I could be mistaken. I'm talking about:

var i: int = method_that_returns_error()

[AThousandShips]

Also the missing Error return is not by design, it's a limitation in the bind system, we cannot currently provide metadata information about binds for these binds specifically

That being said "fixing" that would still be a major compatibility breakage because we cannot guarantee that all extension languages can gracefully handle that kind of type change, C++ can't necessarily depending on what kind of data type is used, i.e. if the enum is class or not