Implement script editor description hint on hover a symbol/word

[ThakeeNathees]

Describe the project you are working on:
Description hint on hover for the text edit(https://github.com/ThakeeNathees/godot/tree/TextEdit-hover-hint)

Describe the problem or limitation you are having in your project:
it's one of the essential feature for a fully featured script editor and currently we lack of. Also the implementation of GDScript doc comments (godotengine/godot#41095) it'll improve the user experience.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:
when a symbol is hovered by the mouse, the text editor emits a signal to validate the symbol (like when it's being hovered with a ctrl), and when validating for that symbol it'll add some additional data (like description, type, class_name, return_type, arguments, etc.,) and display them at the text edit's draw call.

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:
A working example (this will work with doc comments when it'll be merged)

If this enhancement will not be used often, can it be worked around with a few lines of script?:
No, It would be a great usability improvement and can't be worked around with the script.

Is there a reason why this should be core and not an add-on in the asset library?:
there is no way to implement this with an add-on

Bugsquad edit (keywords for easier searching): tooltip

[echebbi]

I'm glad to see that someone is finally working on this, thanks very much for the work!

Would it also be possible associate the "show hint" action to a keyboard shortcut (i.e. show the hint corresponding to the symbol at the cursor's location)? I mainly use the keyboard when coding and having to take the mouse each time I want to check the documentation would be inconvient.

[me2beats]

Providing API for (optional) having this for custom classes and methods could be useful as well

[Calinou]

@me2beats This will probably be done automatically by godotengine/godot#41095.

[ThakeeNathees]

@me2beats yeah it's possible with godotengine/godot#41095 tested locally.
I've exams next month, I'll improve it and implement color themes when it's done :)

[alterae]

Is work on this still ongoing? The last commit in the linked fork was over a year and a half ago

[Calinou]

Is work on this still ongoing? The last commit in the linked fork was over a year and a half ago

@ThakeeNathees has been inactive on GitHub since July 2021, so godotengine/godot#41502 will likely have to be salvaged by another contributor. This won't be trivial to rebase against the latest master branch since the CodeEdit refactor was recently merged.

[Dante3085]

I would really like to have this feature now. Is there any way to make a custom Godot Editor build with the functionality shown in the gif at the top?

[Calinou]

Is there any way to make a custom Godot Editor build with the functionality shown in the gif at the top?

No, as there is no up-to-date branch with an implementation of this feature. As I mentioned above, the script editor received a large refactor last year, so most of the work would have to be redone from scratch.

Efforts to rebase godotengine/godot#41502 against the latest master branch are welcome, but it won't be an easy task.

[jwmcgettigan]

I'm interested in taking a stab at this issue so I've done a quick review of (1) what we already have that is similar, (2) references to the solution in other applications, and (3) the possible features/requirements that may be considered.

Review of Existing/Similar Implementations

1. Generic tooltip

2. Inspector elements tooltip on hover

3. Intellisense dropdown

4. The authoring comment of this issue.

• Implement script editor description hint on hover a symbol/word #1393 (comment)

5. Existing draft for this issue (for Godot 4)

• Implement script editor hover hint with description godot#63908
  • Appears to work only for some functions. Has many issues to iron out.

References

1. Visual Studio (C#)

2. WebStorm (JavaScript/TypeScript)

3. Visual Studio Code (Python)

4. Visual Studio Code (JavaScript/TypeScript)

Review of Possible Requirements

Glossary

Term	Definition
Symbol	A value, function, class, module, or any other construct that can be referenced in code.
Godot Documentation	The official documentation provided for the Godot game engine.
Code Documentation	The comments, annotations, API references, and other documentation created by a developer to explain the purpose and functionality of the code to other developers, as well as to provide additional context and insights into the code.

Implement a tooltip component for symbols.

1. Tooltip Content
   1. Header Content
      1. Derive symbol information.
      2. Derive type information.
      3. Include the icon for the type of item. (e.g. class, function, variable, etc.)
   2. Body Content
      1. Derive Godot documentation.
      2. Derive code documentation.
      3. Prioritize showing code documentation before/above Godot documentation.
         1. Sometimes multiple documentation sources can exist for a single symbol.
            1. Code documentation added to a Godot function. (e.g. _ready())
            2. Overridden function.
            3. Class inheritance.
         2. Consider utilizing tabs to toggle between different documentation.
      4. Consider including an 'Edit on GitHub' link - perhaps in the form of an icon.
         1. Especially if the symbol has no official documentation yet.
   3. Code Documentation
      1. How is code documentation currently parsed?
         1. Here is what the Godot docs say. It mentions that BBCode is used.
      2. How should code documentation be parsed?
         1. It should support the various link types described in requirement 2.2.
2. Tooltip Behavior
   1. Hover Behavior
      1. Implement a delay on hover before showing the tooltip similar to the inspector tooltip
         1. @Calinou Recommends the inspector tooltip's EditorHelpBit.
      2. Keep the tooltip open if the mouse continues to hover over it even if the delay time has passed.
   2. Link Behavior / Types
      1. Symbol Links
         1. Jumps to a symbol's reference location in the code. {Reference 1}
            1. This may move the user to a new script tab.
         2. Jumps to a symbol's reference location in the Godot documentation.
            1. This will move the user to a new docs tab.
      2. Links to external websites.
   3. Show a scrollbar if the body content overflows vertically.
   4. Allow the tooltip to be resizable.
   5. Support nested tooltips.
3. Tooltip Design
   1. Determine tooltip padding, border, and border-radius.
   2. Dynamically adjust height and width to fit content. Set max-width and max-height.
   3. Dynamically anchor the tooltip depending on the position of the mouse relative to the edge of the editor.
   4. The color scheme should automatically adjust to the current theme.
4. Extra Features
   1. Show any errors or warnings (e.g. type hints) related to the function/variable. {Reference 2}
   2. Expandable actions menu. {Reference 2}

Notes

My latest WIP branch for this issue:

• https://github.com/jwmcgettigan/godot/tree/editor-symbols-tooltip-2

My PR Draft

• GDScript Symbol Tooltip godot#80044

Some improvements I'd like to make to this comment include:

• Create some example UI designs for what the tooltip may look like.
• Review and rewrite the requirements.
• Add additional possible features that have been overlooked.
• Add links to any issues or PRs that are relevant.
• Add links to relevant documentation.
• Provide better examples and images.

Question: Should I create another issue or a discussion for the contents of this comment? I'm not sure if the scope of this issue encompasses these possible features and if this is the right place for their discussion in case it leads to off topic comments.

[Calinou]

d. Should there be a delay on hover before showing the tooltip? For example, the inspector tooltip has a delay.

Definitely – I'd use the same delay as GUI tooltips and EditorHelpBits.

In general, I'd recommend reusing the already existing EditorHelpBit rather than creating something bespoke for the script editor. (EditorHelpBit is what's used in the inspector when hovering property names.)

[jwmcgettigan]

Here are some UI designs that I experimented with (using HTML/CSS).

You can find the file or preview it below.

• Gist: https://gist.github.com/jwmcgettigan/3a563a4df07f02c94d5fc866ca43b851
• Preview: https://gistpreview.github.io/?3a563a4df07f02c94d5fc866ca43b851

Notes

• I only implemented an example tooltip for the _ready() function. Nothing else will show the tooltip on hover.
• Styles, colors, and icons are by no means polished. These are just to determine a design direction.
• I plan to change the links and code block styles to mimic the in-editor godot-docs.
• I've added a few more feature bullets to my previous comment.

[Spartan322]

Just to point out I have just rebased godotengine/godot#63908 to master.

[Arecher]

As a side-note, it's worth adding Editor Settings to determine what/how much is shown on the hovers. Personally, I'd never really want to hover and see function documentation. I'd mostly want to hover arguments to see their name and type (especially for custom functions), so a very minimal hover would be preferred.

If the tooltip could automatically adjust it's content based on settings, it could remain one general hover, while still allowing users control over what information they see!

[TheColorRed]

Would also be nice if the tip showed on auto completions as a sub popup.

[jwmcgettigan]

Would also be nice if the tip showed on auto completions as a sub popup.

I presume you mean something like this?

[TheColorRed]

Would also be nice if the tip showed on auto completions as a sub popup.

I presume you mean something like this?

Yup, just like that!

[TheColorRed]

Not sure if it is supported or not (the docs don't show support), so maybe this would be a new proposal, using a @param tag to describe a function parameter would be nice to show in the popup (again similar to vscode).

## Do something with the two colors
## @param color1 Description of color 1
## @param color2 Description of color 2
func fancy_color(color1: Color, color2: Color):
  # Do something with the two colors

So, when creating a JavaScript/TypeScript function, the popup shows like this image, as seen, it auto formats the @param items with the name, and its description.

[Calinou]

Not sure if it is supported or not (the docs don't show support), so maybe this would be a new proposal, using a @param tag to describe a function parameter would be nice to show in the popup (again similar to vscode).

The way Godot class reference docs are written favors documenting parameters inline in the description, using [param name] references to reference parameters in the description.

For example:

## Do something with the two colors [param color1] (which is a fancy color)
## and [param color2] (which is an even fancier color).
func fancy_color(color1: Color, color2: Color):
  # Do something with the two colors