Tooltips for exported variables

[Listwon]

Backward compatible solution to add custom tooltips for exported variables.
Uses comments syntax, so it won't throw errors on previous versions. Tooltips are parsed only in editor. Supports BBCode.

## [b]Tooltips[/b] for exported variables. [br][img]icon.png[/img] [br]With [color=green]BBCode[/color] support. [br]Enjoy!
export var with_tooltip = 2

Related issue #6204

[Calinou]

This looks great! I'm kind of amazed it was that simple to implement. The ## syntax makes sense to me. What does it look like if you wrap the comment over several lines?

Still, we may want to look into adding a basic Markdown -> BBCode formatter. Writing BBCode in comments makes it less readable, whereas Markdown source is still easy to read. Supporting just [b], [i] and [code] is probably sufficient. Many other languages like Rust also support Markdown formatting in doc comments.

[Geequlim]

I'm not sure it is a good idea to add it to PropertyInfo.
As it is not used by properties which are not exported. And it is useless for release version of our games.

In fact you can get the documentations of the exported variables from the LSP extended parser with multi-lines supported.

godot/modules/gdscript/language_server/gdscript_extend_parser.h

Line 94 in 6fcb58f

const lsp::DocumentSymbol *get_member_symbol(const String &p_name, const String &p_subclass = "") const;

godot/modules/gdscript/language_server/lsp.hpp

Lines 1093 to 1115 in 6fcb58f

	/**
	* Represents programming constructs like variables, classes, interfaces etc. that appear in a document. Document symbols can be
	* hierarchical and they have two ranges: one that encloses its definition and one that points to its most interesting range,
	* e.g. the range of an identifier.
	*/
	struct DocumentSymbol {
	/**
	* The name of this symbol. Will be displayed in the user interface and therefore must not be
	* an empty string or a string only consisting of white spaces.
	*/
	String name;
	/**
	* More detail for this symbol, e.g the signature of a function.
	*/
	String detail;
	/**
	* Documentation for this symbol
	*/
	String documentation;

[Listwon]

@Geequlim

I'm not sure it is a good idea to add it to PropertyInfo.

Yeah, I guess it would be better to wrap this in TOOLS_ENABLED block as well.

In fact you can get the documentations of the exported variables from the LSP extended parser with multi-lines supported.

I get it, but the problem solved here is different - to provide the tool to show helpful info in editor, especially useful for non-programmers. As I tried your parser with VS Code it gets the whole comment above the variable. You can't explicitly mark something as documentation, right?

[aaronfranke]

Could this be expanded to be a general system for inline documentation, similar to the /// <summary> XML comments in C#? There's an issue somewhere about generating in-editor documentation for user-created scripts.

[Calinou]

@aaronfranke The proposal you're referring to is godotengine/godot-proposals#177.

[ThakeeNathees]

creating a new token would break the parser unless every corner cases were handled.
ex: if TK_TOOLTIP inside a function (or just a comment starting with ##) the parser complains Expected end of statement after expression, got ... inside _parse_block()
and we check the next and previous tokens for parsing so we need to tell the parser that if it's a tool tip token just skip it.

[willnationsdev]

Is this something that @vnen should be considering as another type of GDScript annotation?

[vnen]

Yeah, this should be added as an annotation.

@ThakeeNathees is working on showing GDScript documentation in the editor as a GSoC project, so a variable description can also be used for the tooltips.

[Vivraan]

Eagerly waiting for this to get merged and usable!

[Calinou]

@SHIVAMMUKHERJEE This pull request will most likely conflict with #39359 and the GDScript rewrite (with the annotation syntax), so I doubt it'll be merged.

[ThakeeNathees]

@Calinou should we consider export variable doc comments as tool tips ?

[Vivraan]

I'll be Waiting for Godot then! As long as I get to use tooltips like a sane person again.

[willnationsdev]

@ThakeeNathees only if the export variable's doc comments are also rendered as editor tooltips. Has that been confirmed by @vnen?

[ThakeeNathees]

@willnationsdev No, I'm just suggesting that to use it as a tooltip yet no decision has made.

[ThakeeNathees]

@willnationsdev , @vnen agreed to use the documentation of export variable as it's tooltip,

here is a working example

[Calinou]

This feature is now available in master (= what will become 4.0 in the future) thanks to #41095.

Should we aim to support this in 3.2? We should aim to use a compatible syntax so that projects can be upgraded smoothly without having to modify the comments.

cc @vnen

[Calinou]

I think this would be a welcome change for 3.4 since the syntax is forwards-compatible with 4.0. However, https://github.com/godotengine/godot/pull/35716/files#r389275266 needs to be addressed before this can be merged.

[Listwon]

@Calinou I fixed auto-rebase issues and the comment with trailing comma in the same line. I've also added the solution for multiline tooltip comments, which you asked about at the very beginning and I missed this earlier.

[DaGamingWolf]

man i would really like this feature. i'm designing an interface for our writers to use without touching much code and tooltips would be massively helpful.

[KoBeWi]

Apparently this implementation works with built-in scripts, unlike the 4.0 one. However, it breaks compatibility, due to the token issue mentioned before. I tend to put ## in comments for stuff I want to check layer, so it's easier to find. If this was merged, all scripts using ## "incorrectly" will break.

[Listwon]

@KoBeWi could you please test those corner cases on newer version of my PR? I found some issues in the release build too, so it should be covered now. Right now it will generate token only if ## comment is just before export variable.

[KoBeWi]

Looks ok feature-wise, but GDScript changes need review.

Also we should probably document this somewhere, including the BBCode syntax (although I assume it's the same as in RTL). Especially the multiline comments might be confusing, as you need to use [br].

[Vivraan]

How difficult is it to make a markdown or even standard XML comment parser?

[Calinou]

How difficult is it to make a markdown or even standard XML comment parser?

There are many Markdown parsing libraries out there, but you'd still have to write the part that outputs BBCode for use in RichTextLabel.

That said, I wouldn't add support for Markdown syntax here, as BBCode is what we went for in 4.0. It's not as human-readable, but it's far more powerful than Markdown could ever pretend to be 🙂

[atirut-w]

If this is to be commented, it will likely cause a similar if not the exact same issue as #66339. I am currently making a fix for the header problem(linked issue) but if I wanna do anything bigger than that it's gonna be a bit of a pain to backport.

Also, this may break single hash docs since the LSP originally used that format.

[geekley]

Does anyone know if tooltips from documentation (e.g. XMLDoc) are available for C# [Export] members in 4.0? I tried a simple test and it doesn't seem like it's supported (yet?).

If not, where is an issue/PR I can watch to track this? Sorry if this is the wrong place to ask. I tried to find a specific issue for C#, but I only found this. Should I open a new issue?

For example, something like this:

///<summary>Tooltip blah blah </summary>
[Export] string myProp;

Or even something like this, if you want to be more flexible?

///<tooltip><summary>Tooltip blah blah </summary></tooltip>
///<remarks>Not in tooltip.</remarks>
[Export] string myProp;

[Calinou]

@geekley It's only supported in GDScript in 4.0. This is not the place to discuss C# support though; please open a proposal for that.

[geekley]

Thanks Calinou! I started writing one, but turns out there is a proposal already: godotengine/godot-proposals#5675
Linking here in case people want to upvote it.

[turbohz]

There's also properties exported via _get_property_list().

Looks like something that should be tightly related, but I'm not familiar with the code.

I wonder if implementing this for those should better be done in another PR,
or could just be done in one go.