Make RST docs consistent with Editor Help docs

[dalexeev]

• Closes Inconsistent Reference Syntax (Proposal) godot-proposals#4116.

Built-in documentation uses a syntax similar to GDScript, while the online documentation uses C-style.

1. Use method_name(param1: Type1, param2: Type2 = default) signature
instead of method_name ( Type1 param1, Type2 param2=default ):

I think parentheses without spaces would look better with a monospaced font.

2. Add tooltip for void type:

3. Use Array[Type] instead of Type[]:

4. Use BitField[Type] instead of BitField<Type>:

5. Highlight pointer types (in extension documentation):

Maybe some other way to highlight is needed. For example bold font, but I'm worried about escaping * and **.

[dalexeev]

See also #80765 (comment). I'm not sure if we should show the full signature, or if we should hide the types and qualifiers.

[YuriSizov]

I'm conflicted about the method signature change because it's still neither GDScript nor C-like. It's still a mix of both, and I don't really understands who does it serve in this form (current form included, not just the changes from this PR).

Specifically, the return type in GDScript would be written in a different way, obviously. But to my taste it makes sense to put it in front of the method. But that's inconsistent with GDScript, though we are not fixing this inconsistency. So making other changes like that seems arbitrary to me. Not that I don't support it, just that I can't define a line other than personal tastes and weak consensus between maintainers.

Then there is 5, which adds a pointer symbol to an otherwise GDScript-like format. This is unusable in GDScript, but it's still written similar to it. This makes me think that C-like is a better common denominator for a language-agnostic documentation.

---

2, 3, and 4 are good. For setters and getters I'd keep the full signature.

[Mickeon]

How do we feel about this? I honestly like all of the changes except the method signature for the same reasons brought up above. I feel like the rest just "read" better for most people.

[Mickeon]

My question from 3 weeks ago still stands. I think anything but the method signature is an objectively good thing. Would be good to rebase.

[dalexeev]

I understand why point 5 is controversial, but I think that points 3 and 4 make no sense without 1, especially since this is how it's done in EditorHelp. We are making the signature more similar to GDScript, the only difference is that the return type is before the method name, because of the table. See also godotengine/godot-proposals#7607.

[Mickeon]

Actually, You know what? Fine. It is consistent with the built-in docs. I was thinking about it for a bit. We shouldn't be afraid to change this. It just plainly looks better. Worst case scenario, it is reverted.

In a perfect world there would be a toggle between GDScript and C# definitions but this is no perfect world.

[Mickeon]

Makes you really think if BitField should have been called BitFlags (on the outside) all along. "field" for these kinds of properties is rarely ever used. Usually they're referred to as "masks", or "flags".
Question for another time, of course.

[dalexeev]

This is the name of the core class. If we ever add such a type to GDScript, it would probably make sense to name it BitField[T] for consistency.

[Mickeon]

I must note, however, I don't think this closes the original proposal. OP still desires the the returned value to be on the right as per GDScript standard.
While that can be done, it needs to first be evaluated, as it would be very alienating for most users. Second, it needs to be well-thought out because with the current way built-in docs display method attributes, doing it won't look pretty.

[akien-mga]

Looks good to me.

[akien-mga]

Thanks!