-
-
Notifications
You must be signed in to change notification settings - Fork 3.5k
Description
Your Godot version:
4.5
Issue description:
The documentation for PackedVector2Array states this:
Note: Packed arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use duplicate(). This is not the case for built-in properties and methods. In these cases the returned packed array is a copy, and changing it will not affect the original value. To update a built-in property of this type, modify the returned array and then assign it to the property again.
Notice the parts in bold. Imo this section needs a slight rewording. The note is probably meant to be beginner-friendly, but it would be nice if it was a bit cleaner. As a programmer I very much expect arrays to be passed by reference because that's how every array type in every programming language works (exaggerating a bit, I know). The exceptional case (that we receive an array copy) is somewhat hidden in the middle of the text -- and it's not really an exceptional case either, because as far as I understand the documentation, it affects all the ways in which I'll receive arrays when I ask Godot to give me one.
I'm not sure how to formulate this better while keeping the beginner-friendliness. Maybe the two cases could be listed as bullet points? That would set them apart visually and elevate them to the same level of importance.
A somewhat related problem exists in the documentation of Line2D. There we have the note replicated, which is actually a really nice idea. Unfortunately it doesn't show up in the editor, which doesn't help very much π
I'm not sure how the editor works, but maybe it suffices to remove the paragraph break? Because as it is right now, I noticed my code wasn't working -> I hopped into the debugger -> I realized points never updated -> I thought "hmm, maybe this is some weird pass-by-copy..."? -> searched online -> and only then realized it had been inside the point-documentation all along π
URL to the documentation page (if already existing):