godotengine / godot-proposals

Godot Improvement Proposals (GIPs)
MIT License
1.16k stars 97 forks source link

Change how operators are formatted in the documentation to match their usage #4219

Open fire-forge opened 2 years ago

fire-forge commented 2 years ago

Describe the project you are working on

Finishing up this PR that adds a GradientTexture2D editor to the inspector: https://github.com/godotengine/godot/pull/58967

Describe the problem or limitation you are having in your project

Operators are currently formatted like functions in the documentation, while their actual usage looks much different.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Example using the float type:

Change the formatting of operators from this:

  float  operator + (right: int)
  Color  operator * (right: Color)
Vector2  operator * (right: Vector2) 
   bool  operator == (right: float) 
  float  operator unary+
  float  operator unary-

To this:

  float  float + int
  Color  float * Color
Vector2  float * Vector2
   bool  float == float
  float  +float
  float  -float

Notice how it much more closely resembles the operators' actual usage.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

This would involve changing the operator names in the XML files for all variant types, and modifying the code that creates both in-editor and website documentation pages to use different formatting for operators.

If this enhancement will not be used often, can it be worked around with a few lines of script?

GDScript can't modify built-in documentation pages.

Is there a reason why this should be core and not an add-on in the asset library?

Documentation is core.

YuriSizov commented 2 years ago

I'm not entirely sure the proposed format would be clear to someone who doesn't know about operator overloading. There is no operative (heh) word there. Maybe it's worth keeping operator but changing the rest of the format as proposed?

So

  float  operator  float + int
  Color  operator  float * Color
Vector2  operator  float * Vector2
   bool  operator  float == float
  float  operator  +float
  float  operator  -float