Code Editor: Add documentation tooltips

[dalexeev]

• Closes Implement script editor description hint on hover a symbol/word godot-proposals#1393.
• Supersedes Implement script editor hover hint with description #63908.
• Supersedes GDScript Symbol Tooltip #80044.

Screenshots

[KoBeWi]

Tested again and it works great now. One major issue is that when moving cursor very slightly the tooltip will disappear, even if you move it over the same symbol. It will open again, but the frequent blinking is bothersome.

Also if you hover a symbol and then move the cursor far away, even outside script editor, the tooltip will still appear.

godot.windows.editor.dev.x86_64_i5Yg4ovIAM.mp4

[dalexeev]

Ready for testing/review.

• Depends on Fix connecting a signal with a double click is too difficult #95044.
• This would go well with Scripting: Fix script docs not being searchable without manually recompiling scripts #95821.
• It also makes sense to separate Ctrl+LMB functions. Say Ctrl+LMB - open the docs and Alt+LMB - open the code.

Along the way I noticed/fixed a few bugs in gdscript_editor.cpp, gdscript_docgen.cpp, and script_text_editor.cpp, but there are still some things that make sense to fix separately, as I'm afraid that this might be a significant refactoring (enums, FQCN).

Also if you hover a symbol and then move the cursor far away, even outside script editor, the tooltip will still appear.

Fixed, thanks.

One major issue is that when moving cursor very slightly the tooltip will disappear, even if you move it over the same symbol. It will open again, but the frequent blinking is bothersome.

I understand that Visual Studio Code does it better (the tooltip doesn't disappear until the mouse leaves the symbol), but I'd rather leave it as is for now. This is consistent with the behavior in the inspector and signal dock, and it's also the same as in Kate.

But most importantly, it's technically hard to do. The tooltip checks if the mouse has left the target. This works for simple controls, but not for Tree and CodeEdit, which consist of many visual parts that are not nodes. Also, TextEdit/CodeEdit allows you to get the symbol at a given position as a string, but has no API to get positional information so we can determine whether it was the same symbol or another such identifier on the same line.

I'd suggest leaving non-critical issues for later PRs, as I don't want to further affect unrelated parts of the engine. In my opinion, this is not a very critical issue, I tried to make it so that the tooltip does not interfere with keys, clicks, scrolling and text selection.

Another usability issue is that TextEdit finds a symbol outside the line:

But the same happens if you hold down Ctrl:

[KoBeWi]

Hovering over variable definition does not show a tooltip. It could be useful when using inference, so e.g. you can hover var something := method() and know the type of something at the source, without having to find its usage.

This is consistent with the behavior in the inspector and signal dock, and it's also the same as in Kate.

For some reason I find it more difficult to see tooltips in code editor than in the inspector. Maybe the minimum movement is too small?

[dalexeev]

Hovering over variable definition does not show a tooltip. It could be useful when using inference, so e.g. you can hover var something := method() and know the type of something at the source, without having to find its usage.

Looks like it's not implemented in the parser:

godot/modules/gdscript/gdscript_parser.h

Lines 1294 to 1298 in 19e003b

	COMPLETION_BUILT_IN_TYPE_CONSTANT_OR_STATIC_METHOD, // Constants inside a built-in type (e.g. Color.BLUE) or static methods (e.g. Color.html).
	COMPLETION_CALL_ARGUMENTS, // Complete with nodes, input actions, enum values (or usual expressions).
	// TODO: COMPLETION_DECLARATION, // Potential declaration (var, const, func).
	COMPLETION_GET_NODE, // Get node with $ notation.
	COMPLETION_IDENTIFIER, // List available identifiers in scope.

When I hover over the variable declaration identifier I get {type = GDScriptParser::COMPLETION_NONE, current_class = 0x0, current_function = 0x0, current_suite = 0x0, current_line = -1, current_argument = -1, builtin_type = Variant::VARIANT_MAX, node = 0x0, base = 0x0, parser = 0x0}.

This and some other issues with incorrect hints are material for future PRs.

For some reason I find it more difficult to see tooltips in code editor than in the inspector. Maybe the minimum movement is too small?

I can't reproduce it on Linux. I encountered this during development, but at some point the bug disappeared.

[AThousandShips]

LGTM

[Calinou]

Tested locally, it works as expected.

Note that you can select and drag code that's behind the tooltip. You also can't scroll the scrollbar that is present for long descriptions, but as the above comments say, it may be better to leave it as-is for now.

Regarding the spawn position of the tooltip, it should probably spawn above the hovered line instead of below. It should also be done at a fixed position (corner aligned to the beginning of the hovered word), not taking the mouse cursor's position into account. This way, you can still look at the lines following the hovered line, which is usually more relevant in most situations. Of course, if there isn't enough space to show the tooltip above the hovered line, then it should be shown below as is done currently.

See VS Code for an example:

Also, there could be a keyboard shortcut to show the tooltip the cursor is under, so that you don't have to open the full documentation page if you're just interested in a single method's description. VS Code uses a dual combination for this (Ctrl + K then Ctrl + I) but I'd prefer something less cumbersome.

[dalexeev]

You also can't scroll the scrollbar that is present for long descriptions

Are you using single window mode? This bug exists from the start. Scrolling should work in multi-window mode.

Regarding the spawn position of the tooltip, it should probably spawn above the hovered line instead of below.

I think it's easy to fix, just change the priority in popup_under_cursor(). I'll take a look later.

It should also be done at a fixed position (corner aligned to the beginning of the hovered word), not taking the mouse cursor's position into account.

This is more difficult to do, I wrote above why. I would prefer to leave it for the next iterations.

Also, there could be a keyboard shortcut to show the tooltip the cursor is under, so that you don't have to open the full documentation page if you're just interested in a single method's description. VS Code uses a dual combination for this (Ctrl + K then Ctrl + I) but I'd prefer something less cumbersome.

I'm not sure I understood what you meant, but we could add a button to the tooltip title or make the symbol name a link:

[dalexeev]

Regarding the spawn position of the tooltip, it should probably spawn above the hovered line instead of below.

I think it's easy to fix, just change the priority in popup_under_cursor(). I'll take a look later.

Done, but I really don't like how it looks. If for short descriptions it looks more or less ok, then for long descriptions it is not convenient. All symbol information as well as brief description (for classes) are located too far from the cursor.

Screenshots

Maybe I am too used to tooltips in Kate, but it seems to me that VSC-way is not suitable here. And I don't really understand what problem this solves? Don't overlap the code below? But the tooltip disappears when you start typing and it is impossible to say which context will be more useful for you at the moment, with the same success it could be the code above.

[Mickeon]

I think of my own personal bias that the tooltip's background is not distinct at all from the Script editor's, at least by default. That, combined with not much inner padding, makes the tooltip look "noiser" than it should, I feel.

[Repiteo]

Thanks!

[Calinou]

I'm not sure I understood what you meant, but we could add a button to the tooltip title or make the symbol name a link:

This is what I mean:

vscode_ctrl_k_ctrl_i.mp4

At the end of the video, I press Ctrl + K then Ctrl + I to make the tooltip appear without having to touch the mouse.

I've opened a proposal to keep track of this: godotengine/godot-proposals#11365

[JekSun97]

Perhaps in the future it will be possible to add this to the help on scripting, for links on functions.

[filkata]

Is a side effect of this that ctrl+click on a function call in my own GDscript code always leads to the documenation rather than the code for the function itself like before? I would like to know if there is a way to get the old behaviour as this severely afects my workflow.

[KoBeWi]

#100707