Tooltip for exported variables

[Kazuo256]

Operating system or device - Godot version: doesn't apply

Issue description (what happened, and what was expected):

I couldn't find one, so I wanted to open an issue for this entry in the site's Q&A:
https://godotengine.org/qa/313/tooltip-documentation-custom-exported-variables-gdscript

Basically, would it be possible to add a feature for specifying custom tooltip texts in exported variables?
The main motivation is to improve communication between team members inside a game project, particularly between those that produce development tools and those that use them.

Steps to reproduce: doesn't apply

Link to minimal example project (optional but very welcome): doesn't apply?

---

Thanks in advance!

[Zylann]

Could we use docstrings for this?

[vnen]

Could we use docstrings for this?

Well, if you're willing to implement such thing in GDScript... Not that's a bad thing, but it'll require some work.

[Zylann]

Ooops, I thought GDScript supported docstrings? I've seen the code editor color patterns like """test""" in the same color as comments, and I found some in Akien's Logger plugin. But if it's not... well yeah, it's a bit of work.

[RebelliousX]

It would be great to take a comment (1 line or multiple) that precedes the exported variable as a tooltip. The same way Visual Studio is handling that. In fact, it would be nice to have tooltips for all variables that have comments.

[Zylann]

It can be nasty if the comment is actually not intented for the variable (TODO item or commented code before the variable). That's why I recommend docstrings, and also ignoring those that are more than 1 empty space above the documented member.

[Sslaxx]

This sounds more like it's leaning more towards a general code documentation issue.

[RebelliousX]

@Zylann Not really, the script editor should ignore empty lines above variable declarations. Besides, comments directly above variables (without empty lines) that don't relate to them are bad anyways.
It wouldn't require much work for Godot to implement that.

Or if that really not feasible, the comment can be on the same line after the declaration, but would be harder to do multiline tooltips that way.
export var h_scroll_spd = 10 # Horizontal scroll speed

[Zylann]

After thinking a bit you're right that commented code won't show up because this looks confusing anyways:

# Testing var
#export var test = 1
# Does things if you set it to 43
export var test = 42

And you would put a blank line between the two.

If we can't distinguish between doc comments and simple comments, there will be cases where the editor will show both. I remember this case:

# TODO Change this to a string after the next release
# Does things if you set it to 43
export var test = 42

TODO will end up in the tooltip.

Also, consider this:

# This is one
export var one = 1 # TODO We should make an array
# This is two
export var two = 2

Only comments with nothing else but space on the left should be picked.

Also, I don't think an alternate syntax for doc comments is harder to do, because with only one kind of comment you have to handle a few more cases anyways.

[bojidar-bg]

@Zylann Well, we can easily have #@ or ## for doc comments, but IDK

[RebelliousX]

What I am saying is, doing tooltips through comments should be effortless and painless with little to no interactions by user. If the user is getting wrong tooltips because of sloppy coding, then it is not Godot's fault. It will take 3 seconds to spot that there is something wrong with the definition of the tooltip and the user will rectify that by adding a preceding empty line. Also, it should be mentioned in the documentation/tutorial about this behavior, to let new users be aware of this. Most of existing users will see and recognize how it works almost immediately.

Nothing is wrong with copying successful products such as Visual Studio. It is not about imitating a software, but just Keeping It Simple (KIS) "without last s" :)

Edit: Also, Visual Studio can detect either of the comment preceding the declaration or the one in the same line after the declaration and use that as a tooltip. So, yes, if it works there, it should for Godot.

BTW, Doxygen is horrible IMHO.

[Sslaxx]

I think copying Doxygen, rather than VS, might be more useful here.

[footurist]

Is this still on the table? Is anybody aware of alternatives that are possible right now?

[Larzans]

This would be a very useful feature, as it would help a designer to understand what the variables are for without having extremely long descriptive names for them.
I have not found any way to do this with GDScript
+1

[nicktgn]

How about for starters add the tooltip as an optional parameter to _get_property_list(), since lots of things seems to be done exclusively through it anyway?

Example:
We can add tooltip to a custom resource property so that we know which custom resource to choose from in the inspector, since currently there is no way to export a specific custom resource type, not even by adding a custom type via EditorPlugin ( #22641, #22660, #24319, #24643, and probably some more related issues).

var my_custom_res:MyCustomResource

func _get_property_list():
     return [
         {
             "hint": PROPERTY_HINT_RESOURCE_TYPE,
             "usage": PROPERTY_USAGE_DEFAULT,
             "name": "my_custom_res",
             "type": TYPE_OBJECT,
             "tooltip": "resource of type MyCustomResource" 
	}
    ]

[Zylann]

How is Godot doing this currently? I think it uses the documentation data, but there doesnt seem to be a way to provide this data in such a way that there is a workable single source of truth. By workable, I mean for Godot C++, it's the XML files. For GDScript, it could be that, or docstrings/comments. Both have the advantage of allowing generation of doc both in the editor and standalone documents.

In any case I would not want to write all the doc for my plugin twice :p

[burstina]

this feature would be really helpful.. and it is pretty old.

no milestone for this?

[cchipont]

Any idea if this is considered in the roadmap ?

[Calinou]

@cchipont As far as I know, this feature isn't listed on the roadmap. This doesn't mean it won't be added; someone just needs to come up with an implementation that gets merged 🙂

[PLyczkowski]

I would be ok with comments on the same line as the exported var be used as the tooltip:

[Calinou]

@PLyczkowski This could be problematic for long descriptions, so descriptions on the previous line should be supported as well.

[girng]

If working in teams, I think it's sufficient for a developer to add a bit of information above the export line. IMO, a variable which is concise and brevity inducing, is far more imperative than custom tooltip text.

[Calinou]

@girng There are many cases where you can't explain what an exported variable will do in 1-3 words 🙂

Supporting custom tooltips will make artists/level designers more productive, so they don't have to look at scripts to know what exported variables do (as long as the programmers documented the variables).

[girng]

Eh, fair point.. But a simple documentation above the export line feels sufficient to me. I mean, that's what comments are for. But you are also correct if a designer doesn't want to peddle around in the script file.

[Zylann]

Those comments can also be used as documentation, which is what the tooltips of builtin classes are derived from.

[UnityFuchs]

Tooltips are so important.
Keep the overview of your project and let other know what your vars do.
I'm ok with any kind of tooltip, just make it possible, please.
tooltip, [tooltip], #tooltip, ...

[thinkier-tim]

Please forgive my brazen intrusion.

First, I'd like to state that I know this isn't high on the priority list, but I feel like it would be a huge Quality of Life improvement; the ability to let the artist or level editor or any non-programmer contributor know what happens when they change an exported script variable (without having to constantly refer to a separate document) would just make so many things so much easier that I couldn't resist saying a few words on the subject. For that matter, a note to myself about what an exported variable does without having to go look at the script could be extremely useful, on occasion.

Now that I've had my little soapbox moment, let's get to the part where I throw darts in the dark:
The thought occurs to me that a Node object has an "Editor Description" property, which can be used to add hovertext to a Node in the Scene Dock. Could something similar be done for exported vars?

I haven't looked at the source, but I have noticed some built-in properties already have some sort of explanation of what they do; for example, Node also has a "Process Priority" property that has explanation hovertext in the Inspector in addition to the property name.
How is that implemented?
How hard would it be to give access to that functionality to a tool script?
Alternatively, how hard would it be to add an editor_description property to exported vars (perhaps with some tweaks to the export keyword?) and would that be sufficient to get this working?

... and now I'm running off to look at the source... Okay, now I've (briefly) looked at (some of) the source. Lines 1968-1979 of scene/main/node.cpp have some sets/gets for editor_description, which appears to be metadata. I'm not going to dig around looking for where that data is used, but I now have some more thoughts.

After reading about object.set_meta, it feels like we could almost just test.set_meta("editor_description", "hovertext goes here") - except that throws an error, apparently because primitives (String, int, et al) don't have a set_meta()? I am not being sarcastic when I ask, "How hard would that be to rectify?"

It would be fantastic if we could export a var with the editor_description text on or near the same line that declares it. For example:
export var the_answer = 42, "The answer to the ultimate question of life, the universe, and everything."

or perhaps we could export a description metadata with the same name as the var:

export var the_answer = 42
export description the_answer = "The answer to the ultimate question of life, the universe, and everything."

but in my (obviously not-so-humble) opinion, having the functionality at all should be the priority.

I (and likely many others) would be absolutely thrilled at the prospect of being able to do even something like the following:

tool
extends Node

export var the_answer = 42


func _ready():
    the_answer.set_meta("editor_description","The answer to the ultimate question of life, the universe, and everything.")

related musings:
set_meta("_editor_description_", "This is the editor description for this Node.")
The above line works just fine if used in a tool script attached to a Node; the Node's editor_description changes, which means the tooltip for the Node in the Scene Dock changes (Of course, the scene has to be closed, then re-opened to reflect this change, as all tool scripts currently do - that's a separate issue, for which a simple workaround exists). One could simply manually change the "Editor Description" field in the Node's properties in the Inspector, but the script works... Much to my chagrin, there's no similar Editor Description property field for exported Script Variables.

Edited to add:
Oh, and one more thing: Listwon's BBCode-enabled tooltip PR looks phenomenal.

[carlosribeiro1987]

I like the VisualStudio XML doc comments, I believe that would be a good feature in GDScript. Inspired on VS style (and using the same tags), I think the concept below would be great.

## <summary>
## Game gravity.
## </summary>
export(float, -100, 100) var Gravity = 20

## <summary>
## Player jump height.
## </summary>
export(float, 0, 30) var Jump_Heigth = 4;

## <summary> Some function. </summary>
## <param name="param1"> First Parameter. </param>
## <param name="param2"> Second Parameter. </param>
## <returns> The function return value. </returns>
## <remarks> Code from Godot docs. </remarks>
func some_function(param1, param2):
    var local_var = 5
    if param1 < local_var:
        print(param1)
    elif param2 > 5:
        print(param2)
    else:
        print("Fail!")
    for i in range(20):
        print(i)
    while param2 != 0:
        param2 -= 1
    var local_var2 = param1 + 3
    return local_var2

[Calinou]

@carlosribeiro1987 There's more discussion about this in godotengine/godot-proposals#177, but I don't think XML is the right choice here as it's quite verbose. That is, especially in a language which stands against verbosity like GDScript 🙂

[Calinou]

Note that this was implemented in 4.0 by #41095.

[Totobird-Creations]

I know I'm a "little" bit late, but I did create an addon that does this in Godot 3.4.
It does exactly what you seem to want.
https://github.com/Totobird-Creations/Godot-GDScript-Plus

[Giwayume]

Can we get this official for the 3.x branch please?

[Calinou]

Can we get this official for the 3.x branch please?

There's a 3.x implementation of this feature, but it needs a full review before it can be merged for 3.6.