Add further details on properties returning Packed*Array

[AThousandShips]

Limited it to properties with setters and existing documentation, might be excessive but without some central point to point to explaining this I feel this is a relevant point to clarify generally (also easier to access the information from the built-in documentation)

Left the documentation for Gradient as is as it has more specific details, could possibly add specific details to some of these if they have specific setters for details, but left it simple for now

• Closes: Direct manipulation of Polygon2D polygon array elements possible in GDScript but not in CSharp. #85198

[Mickeon]

I don't know how to feel about this. The note of this PR talks about "returned values" and "methods", but the subject is always a property. The meaning of the note can only be inferred if you know what setters and getters are, and is otherwise still a bit puzzling.

Also consider that both GDScript and C# discourage using setters/getters for built-in classes whenever possible, in favour of properties.

[AThousandShips]

This is an existing note applied to more places, I didn't write this just updated one and copied it around, this was done in (and has been in there for almost 5 years):

• Add some documentation for methods that return Copy-on-Write arrays. #26043

[Mickeon]

I'm aware it does exist elsewhere, I am just a not fan of the way it is worded when applied to an Object's properties.

[YuriSizov]

I mean I get the issue, but adding this note to absolutely every case of using packed arrays in the entire Godot API seems like an overkill.

[AThousandShips]

Can work on the verbosity, or add a note to the packed arrays themselves and link to it instead, but this thing has caused a lot of confusion and I think just putting it in the manual isn't enough (and it isn't there yet either)

[YuriSizov]

Yeah, I am familiar with the kind of confusion it can cause, been there 🙂 But from the maintenance perspective this is unrealistic to keep up and keep in sync. Should we work on a more general solution if a method returns a value vs a reference? That way we could automate the notes/visual indication in the docs.

Edit: Although here it's members, and not methods, which makes it even worse. I dunno, maybe this is the only way.

[AThousandShips]

Could have an automatic addition, can look into that, but I think important to have self contained in the built in docs

[AThousandShips]

Thinking an addition to all the Packed*Array classes on the lines of:
Note: Even though Packed*Array is shared like Array (any modifications to one changes all copies, unless duplicated with duplicate), a Packed*Array returned from a property or from built-in methods it is copied from the original, and modifying the returned array will not modify the property, instead make your modifications to the returned array and then assign it to the property again.

Or something, will see the wording in Array, and then maybe an automatic addition on properties returning a packed array type, that might be intrusive but will see, for translation it should be in the file id say

Perhaps an automatic message of:
Note: The returned Packed*Array is not shared and updates to it will not update this property, see Packed*Array for more details.

[AThousandShips]

Added notes to Packed*Array and will look at adding automatic details to properties next

[AThousandShips]

Added an automatic note in the built-in documentation, will see how to implement the same for the rst generation etc., if this is the way to go

Will also remove notes that already exist

Any suggestions on either wording is welcome

[AThousandShips]

Restricting to built-in classes at the moment, as from what I can tell at least for GDScript the data isn't copied like this but remains shared, but will investigate further as well

[AThousandShips]

Not extremely familiar with the doc generation system but attempted to add the same feature to the rst side, any hints would be very welcome

[Mickeon]

Looks great and has been needed for a while.

[AThousandShips]

Someone well versed in the rst generation and style would be appreciated to take a look at that side, it looked like it works correctly but I haven't worked with that side properly

CC @Calinou I believe you've done some work in this area

[Calinou]

Tested locally (rebased on top of master 29b3d9e), it works as expected.

[mhilbrunner]

Commits need to be squashed, besides that and the small note above this LGTM.

[AThousandShips]

Good, had separate commits for specific things, will fixup and squash

[akien-mga]

Needs rebase.

[akien-mga]

Thanks!

[AThousandShips]

Thank you! Great to get this merged, learned entirely new areas of the system