Improve autocompletion display in the script editor

[Lazy-Rabbit-2001]

Describe the project you are working on

GDScript source-code debugging, GDScript-based projects

Describe the problem or limitation you are having in your project

This topic started from godotengine/godot#98557 and dev chat when I posted some progress about using different color to distinguish private and protected members from normal ones. That day, Mickeon mentioned unwield auto-completion of GDScript: The icons "are not good to glance at." (Mickeon)

Meanwhile, the incoherence of typing signature beginning with _ after func has brought extending question: If you looking at literally the identifiers in the auto-completion list, chances are that you cannot quickly distinguish properties from functions and signals, because they don't have () as the ending, which also makes the icon completely an attribute rather than hinter.

So, it's time to get everything improved.

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

1. Adding brackets after the identifers of functions and signals. If the method contains arguments, adding ... in the brackets (Done):

f() | set_process(...)
f() | is_processing()
·))) | timeout
·))) | area_entered

2. Distinguishing constants, variables, enums, callables, and signals from each other with distinguishing icons. (Some have been made and needs remarks and discussion)
3. Improve argument passing-in, which includes:
   a) When the argument requires a type, displays the best-match result and then other type. for example:

func my_func(test_int: int) -> void:
        pass

func run() -> void:
        my_func(->)

Here -> will display the properties in int type first and then the other types.
b) When it requires a callable, using callable icon for the methods displayed:

        # extends Node
        # Some function that requires a callable
        call_func_arg_callable(->)

where -> will be like:

🔈| add_child(...)
🔈| is_inside_tree()
...

And remove the braces on tabbing.
(Not sure if a .bind() should be inserted after a callable with arguments)
4. Like VS2022, improve completion of some control-flow keywords, which is an option settable in editor settings:

[tabbing on `if`]:
if x:
       pass
else:
       pass

[tabbing on match]
match x:
        x:
                pass
        _:
                pass

[tabbing on for]
for i in x:
        pass

[tabbing on while]
while x:
        pass

More will be added, feel free to propose your idea here :)

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

The gdscript_editor.cpp and editor_theme_manager.cpp are the main places to achieve this, and by editing the relative code pieces, this will be done as quick as possible.

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

No, as this requires modification of source code.

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

This requires modification of source code.

Pull-requests:

• Adding braces for methods
• Unique and distinguishing icons for keywords, control-flow words, annotations, constants, variables, signals and functions (callables).
• Improve the completion option sorting to match the best one for the current argument in a function.
• Optional function of advanced completion for some of control-flow words, which is configurable in the editor settings.

[HolonProduction]

1. Adding braces to methods sounds like a good idea.

2. When it comes to the colors, I'm not a fan of this. Personally I find the x,y,z coloring harder to read and it doesn't help me (it might be more help full when having the script editor as floating window, and the 3d or 2d view with colored axis on the screen while coding 🤷). However when it comes to the completion types mentioned here, there are no established color codes which could help or could be referenced. I think it would make scanning through options harder.

3. _init and _static_init are only really relevant when implementing virtual methods. When they occur as identifiers in a suite they have no special importance, so highlighting them there doesn't make much sense to me. When overriding a method, the user already started by typing the func keyword and therefore is likely to have a method in mind, so highlighting them here seems superfluous to me. Furthermore giving special color treatment to certain methods in the completion has the risk of making users think that it has some special meaning, but there is no documentation to look at, so users will just be asking themselves why those methods are treated differently. Highlighting important methods should be done in the docs description were we can explain why methods are important IMO.

4. What problem does this solve? Annotations are never mixed into other completion options since their context is pretty much unique. This would just make reading harder and gain us nothing IMO.

Overall I'm against colored text in the completion options. However I think we could combine the idea with the fact that our completion type icons tend to be hard to distinguish at a glance. Maybe adding differently colored circles behind certain completion icons could make it easier to tell the types apart, while still maintaining readability.

[HolonProduction]

Why should signals be displayed with braces? The only context where this is valid is the declaration, which doesn't get autocompletion. I believe the display text should be a representation of what the user is going to get, not of how it was declared.

[Lazy-Rabbit-2001]

Why should signals be displayed with braces? The only context where this is valid is the declaration, which doesn't get autocompletion. I believe the display text should be a representation of what the user is going to get, not of how it was declared.

Then what if a signal contains arguments? If a signal does not contain parameters, I think yours would better, but when it comes to one with them, would a user will know from autocompletion if this signal contains arguments, without checking docs?
Imo a display text of autocompletion should not only hint what a token is, but also what it would contain, therefore a user can quickly realize that "Uh! It has multiple elements and I need to insert something in its emit(), or callback arguments". This is friendly especially for new users, and somewhat a kind of protectional hint.
As for how to achieve this in a better way, tbh I have no any better idea. I thought of using <...> but this would be overlapping with the grammar to declare a generic type. [...] and {...} are even worse, ofc...

[HolonProduction]

This really seems like you are trying to compensate for missing features to easily inspect documentation. Autocompletion, in the first place, is a list of options to insert, not a way to view documentation (yeah I also love to scroll through it instead of looking at the docs 😅, but this isn't the most important usecase). I don't know any editor that would toss those things together.

E.g. VSCode (and thus most LSP based editors) has an additional window for documentation info of completion options:

E.g. IntelliJ has a distinct position for type information, and in addition uses grey colors to separate what you are going to get.

I'm not against displaying such information, but the display text isn't the place for it IMO. Adding braces to method calls there makes sense and is what the user will get (although I'd love to use a grey color for the braces, to highlight the method name). But if we want to show more information to the user, it needs a clearly separated space in the UI.

As for how to achieve this in a better way, tbh I have no any better idea. I thought of using <...> but this would be overlapping with the grammar to declare a generic type. [...] and {...} are even worse, ofc...

GDScript has no <> generic syntax, but I agree that it might get confusing for people who also use other languages. The best way here would be a visual difference similar to how inlay hints in other IDEs display, but that isn't really possible with the current UI afaik.

[Lazy-Rabbit-2001]

Added some new improvements I thought can be done in the future. For the improvement of method adding braces following, see the pr godotengine/godot#99102
The rest of the listed proposals will get pr-ed one by one

[HolonProduction]

What you suggest in 3. is tracked in #10665

What you suggest in 4. would basically be snippets like in #2402

[Lazy-Rabbit-2001]

godotengine/godot#94196 has implemented an icon for local variables, which is also a part of this proposal. Thanks the author for this contribution :D