Implement script editor description hint on hover a symbol/word

ThakeeNathees commented 4 years ago

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 (https://github.com/godotengine/godot/pull/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) hint2

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 commented 4 years ago

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 commented 4 years ago

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

Calinou commented 4 years ago

@me2beats This will probably be done automatically by https://github.com/godotengine/godot/pull/41095.

ThakeeNathees commented 4 years ago

@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 commented 2 years ago

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

Calinou commented 2 years ago

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 https://github.com/godotengine/godot/pull/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 commented 2 years ago

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 commented 2 years ago

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 https://github.com/godotengine/godot/pull/41502 against the latest master branch are welcome, but it won't be an easy task.

jwmcgettigan commented 1 year ago

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.

https://github.com/godotengine/godot-proposals/issues/1393#issue-682448616

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

https://github.com/godotengine/godot/pull/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.

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.
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.
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.
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

https://github.com/godotengine/godot/pull/80044

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

[x] Create some example UI designs for what the tooltip may look like.
[x] 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 commented 1 year ago

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 commented 1 year ago

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

chrome_2023-03-14_00-44-32

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 commented 1 year ago

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

Arecher commented 1 year ago

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 commented 1 year ago

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

jwmcgettigan commented 1 year ago

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

I presume you mean something like this?

Code_2023-07-26_00-13-46

TheColorRed commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

devchenli commented 4 months ago

It has been 3 years and this feature has not been officially launched yet. It seems that Godot still has a long way to go. Thank you to those who have contributed to this feature.

godotengine / godot-proposals