property_can_revert and property_get_revert are not documented features

[willnationsdev]

Godot version:
3.2 stable

OS/device including version:
N/A

Issue description:
I noticed that this property_can_revert method exists to forcibly override the Inspector's behavior in regards to an Object's revertability of a given property. You can then see it used with property_get_revert to actually set the value upon reverting. These are not documented features and should be added to the API docs somewhere.

N/ASteps to reproduce:

Minimal reproduction project:
N/A

[Xrayez]

Is this relevant for built-in classes or scripting as well?

I'm asking this because internal callbacks can be actually overridden via GDScript but still be "private": #42968.

[willnationsdev]

@Xrayez
I haven't tested it yet, but there's someone on Reddit who was encountering an issue and I suggested he give it a shot. I have a feeling it should be accessible from scripting cause it uses has_method and call on the Object which should defer to the script first before checking the C++ instance.

[akien-mga]

For the reference, it's used (and documented) in those three classes:

doc/classes/ProjectSettings.xml
115:            <method name="property_can_revert">

doc/classes/EditorSettings.xml
119:            <method name="property_can_revert">

doc/classes/ShaderMaterial.xml
22:             <method name="property_can_revert">

It's used with call because it can't use this as a method since only 3 classes implement it. I don't think it was meant to be used in scripts or other types of nodes.

It might be usable in scripts as a consequence of implementation, but it doesn't look like it was designed to be so. We can consider changing that but it's a feature request more than missing documentation. It would imply making this a method of Object instead of having it implemented only in the few classes where it's currently used.

[willnationsdev]

@akien-mga Ahh, that makes more sense. It'd have to change how it is used in the Inspector then, cause right now it assumes the existence of the method is, itself, an indication that it should override everything else. I suppose the logic would need to separately check if there is a script and if the script instance has the method and can call it, etc.

[AnidemDex]

For now, they are useful when you work with custom classes, see #30440 (comment)

[akien-mga]

This should be done for 4.0 IMO.

I would suggest exposing _property_can_revert and _property_get_revert (note the leading underscore) as virtual methods in Object in the same way that _get_property_list is implemented. Given how core Object is it's maybe more convoluted than just using GDVIRTUAL_BIND/GDVIRTUAL_CALL, at least that doesn't seem to be used in Object's current virtual methods.

[AnidemDex]

Can it be something like

func _get_property_default_values() -> Array:
    return [{"name":property, "value":default value}]

or should I open a proposal for it?
Currently I have to do something like this, twice, for each property; One for telling that it has a default value, another to return the default value.

[YuriSizov]

Can it be something like

Not without major core changes.