Add a note about _notification() being multilevel

[KoBeWi]

No description provided.

[Mickeon]

It's not the only one, is it?

Also, this information feels more pertinent to mention in detail in notification instead (and it is), as it explicitly describes how that method works. But it is true that this virtual method is the odd one out, so a shorter note is due.

[KoBeWi]

It's not the only one, is it?

I don't know any other method like that. Even _init() isn't multilevel.

Also, this information feels more pertinent to mention in detail in notification instead

To me this odd behavior is useful, because you can override this method without worrying that some extending script will replace its behavior, which gave me idea to add the note. Maybe _notification() could be linked in some other methods, like _ready() etc.

[Mickeon]

Not denying the usefulness of this behavior at all. In fact I know someone that used this to explicitly avoid having to write super() every time.
But I am not convinced a note is the right place to provide a example use case. In the current PR, it's somewhat hard to understand and envision. At the same time, providing a more meaningful example may be too much.

Rather, it should probably just mention that this behaviour exists and it's an exception.

[KoBeWi]

I don't know any other method like that.

I just remembered that the property methods are multilevel in C++. I tested them and _get_property_list(), _property_get_revert(), _get() (and probably _set()) are also multilevel in scripts. _validate_property() and _property_can_revert() are not (bug?).

Should they get a similar note? I wonder if we could mark these methods as multilevel, similar to virtual, const etc.

[Mickeon]

Should they get a similar note?

Probably, yeah. The note itself could be made more generic for the sake of maintainability.

I wonder if we could mark these methods as multilevel, similar to virtual, const etc.

I think a special qualifier would need extra scrutiny as that would require a new method flag (unlike #107130).

_validate_property() and _property_can_revert() are not (bug?).

I swear this has been discussed in the past, but I can't find an issue. Something about how some methods are still "multilevel" despite the transition to Godot 4.0, and how it can't be changed now for fear of compatibility breakage.

[KoBeWi]

Probably, yeah. The note itself could be made more generic for the sake of maintainability.

Something like

[b]Note:[/b] Unlike most virtual methods, this method is called automatically for every extended script. This means you should not call the base implementation via [code]super[/code] in GDScript or its equivalents in other languages.

?

I think a special qualifier would need extra scrutiny as that would require a new method flag

Not really, it could be added manually, like deprecated flags. I know it's not very maintainable, but we have very few such methods and I think we didn't add one since 3.0, if not longer.
EDIT:
Well, _property_get/can_revert() has been multilevel for 2 years actually. That's still quite long though.

[Mickeon]

This PR is good as is, but yeah, this oddity should be mentioned in those respective methods. Maybe asking @vnen for details later?

Only personal gripe is that with the current wording it may be implied that only super() is wrong, but calling the parent method directly (super._notification()) is fine, but... eh.

[KoBeWi]

calling the parent method directly (super._notification()) is fine

That still involves super.

[Repiteo]

Thanks!