Vector types unary not operator documentation is inconsistent

[meticoeus]

Your Godot version: 4.1

Issue description: The Vector 2 and 3 (and the int counterparts) class documentation for operators is missing a description for the unary not operator, not value / !value. There is a note at the end of the class description describing the behavior of boolean coercion but the first place I looked for what !value did was the operators section. It may be helpful to add bool operator unary! ( ) to the unary operators section and describe the result and/or reference the note for boolean behavior. If the maintainers agree, it may be a good idea to apply this addition to all types/classes that support boolean coercion.

URL to the documentation page (if already existing): https://docs.godotengine.org/en/stable/classes/class_vector2.html https://docs.godotengine.org/en/stable/classes/class_vector2i.html https://docs.godotengine.org/en/stable/classes/class_vector3.html https://docs.godotengine.org/en/stable/classes/class_vector3i.html

[AThousandShips]

~The Boolean context part isn't an operator, it's a feature in GDScript, there's no Boolean not operator for these types~

It is a more specific operator, but it might be confusing due to syntax, in fact this is done by choice, as per this comment in the doc generator:

// Showing above 'and' is pretty confusing and there are a lot of variations.

[meticoeus]

Can you provide a reference to where that comment is located? I couldn't find it and I currently don't see how it applies to documenting '! / not' on Vectors, or any type that has well defined boolean coercion behavior.

Boolean context doesn't need to be mentioned if there is concern that it would lead to confusion. The operator itself has a well defined signature and behavior like the others that are documented.

I propose the below documentation for Vector2:

bool operator unary! ( )

Returns true if the Vector2 is equal to Vector2(0, 0). Otherwise, it will always return false.

In what way is this confusing?

I also notice that unary ! is not documented for the bool type. While you could argue that documenting it is trivial and unnecessary, other trivial operators like float operator + ( float right ) for float is documented. I'm in favor of documenting the trivial operators so that new users reviewing the documentation can see all of the operators that apply to a type and their precise behavior, which has generally been added in Godot 4.

[AThousandShips]

It's here

But it does apply, it literally is where the documentation is generated, you can't have these operators documented otherwise

[meticoeus]

Thanks for the link. I agree with the comment that OP_AND, OP_OR, and OP_XOR would just generate noise with all of the variations that exist. No comment on OP_IN and OP_MAX; I'm not that familiar with them.

OP_AND, OP_OR, OP_XOR are all binary operators with a large number of types they interact with determined by their behavior in boolean context. OP_NOT is a unary operator that has a single operation signature for each type that supports boolean coercion behavior so the comment that "there are a lot of variations" doesn't apply to this one the way it applies to the other 3.

[AThousandShips]

I disagree that this is needed generally, and it's one exception where it applies to all the rest

[meticoeus]

I disagree that this is needed generally

On what basis? Why should ! ( ) be excluded when float + float is documented? They are both equally obvious to anyone with sufficient experience with the language. Vector2 * Vector2 is not obvious as it is not a common vector math operation so documenting it is important, otherwise someone might read it and assume it was the dot operator as it is in some languages.

[AThousandShips]

Because it's trivial, most of the time, so adding it specifically to the docs makes more sense, most types have an obvious bool operator

[meticoeus]

I originally asked this question filed this issue precisely because it wasn't obvious what ! (Vector2) did. After not seeing it documented in the unary operators section I scanned the rest of the page looking for any mentions of boolean behavior and found the note in the class description. I argue this is less discover-able than just including it in the operators section since ! is a unary operator and there is already documentation for other type supported unary operators, even when their results are trivial.

[AThousandShips]

For this the operation is pretty obvious though, !vec is equivalent to vec == Vector2()

Can change the generation system but it's a bit of extra tweaks and details for a relatively specific and niche thing

[meticoeus]

It is only obvious once you know how Vectors are coerced to boolean values since they can't be null so the usual behavior for objects doesn't apply. Maybe only include the operator for non-nullable types since these have relatively surprising boolean coercion behavior?

[AThousandShips]

This is the case for all non-Object types, we can't selectively include or not these though, that's not how it works with generating

We can add a different way of handling the generation so the not operator is generated, but I think it's better to have it be a note like it currently is