Add descriptions/tooltips to editor settings

[EricEzaM]

Describe the project you are working on:
Using the Godot engine.

Describe the problem or limitation you are having in your project:
Sometimes it would be helpful to have additional information/context about editor or project settings.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:
Add ability to set descriptions for these settings which show up in the tooltip when hovered.

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:
Not the best example but you get it. Most properties have self-explanatory names, but some could do with some additional context.

In code:

If this enhancement will not be used often, can it be worked around with a few lines of script?:
N/A

Is there a reason why this should be core and not an add-on in the asset library?:
Part of the editor.

[bojidar-bg]

Project settings already have tooltips, which are defined in the documentation:

https://github.com/godotengine/godot/blob/69c81309cc786cc5702fb8d558636fb31f207971/doc/classes/ProjectSettings.xml#L207-L209

Perhaps, something similar can be done for EditorSettings as was done for ProjectSettings here: https://github.com/godotengine/godot/blob/69c81309cc786cc5702fb8d558636fb31f207971/editor/doc_data.cpp#L287-L291

[KoBeWi]

Related: godotengine/godot#29694

[Calinou]

Perhaps, something similar can be done for EditorSettings as was done for ProjectSettings here: godotengine/godot@69c8130/editor/doc_data.cpp#L287-L291

Unfortunately, you can't just move the EditorNode registration around as the engine will crash on startup if you do that. (I tried doing that a while ago.)

[EricEzaM]

Ok, so I just slapped something together to "brute force" a solution. It works... but lay it on me if this is a bad idea:

In doc_data.cpp I just added these:

if (name == "EditorSettings") {
    EditorSettings::create();
    EditorSettings::get_singleton()->get_property_list(&properties);			
    own_properties = properties;
}

Just before this:
https://github.com/godotengine/godot/blob/69c81309cc786cc5702fb8d558636fb31f207971/editor/doc_data.cpp#L287-L290

And it works. Docs get generated with all properties... I can add descriptions in the xml and it shows up in the editor settings at runtime, all that good stuff. No build/compile warnings. Obviously this is hacked together and I would need to clean it up a bit, but I just figured since all we need to get properties when using --doctool is a created instance of EditorSettings, why not just do that?

Edit: ok so I guess one issue is that the EditorSettings is now registered and created in DocData every time... which is kinda dumb. I was hoping I could make a "temporary" instance of it.

[EricEzaM]

Ok so basically at this stage it looks like it is impossible to get all editor definitions when you run the doctool. You can get the ones created in the constructor of EditorSettings and create() which come from calling _initial_set(), but there are so many other definitions, like ones defined in editor plugins which are never loaded, due to the editor itself not starting up when the doctool is run.

For example, editors/3d_gizmos/gizmo_colors/navigation_edge which is defined in the constructor NavigationRegion3DGizmoPlugin() is actually created on SceneTree::init(), which is not called at all when running doc tool, since it does not load the editor.

To summarise, it seems that with the current system, if we wanted to get editor definitions from the doc tool, only about 200 would be able to be included. The other one hundred (approx) come from editor classes which register their settings in their constructor (or other setup) and as a result are not done before the doctool is run.

So some options would be:

1. Make the doctool start the editor before running so all these classes can have their settings registered before DocData::generate() is run; or
2. Include documentation in-line, in code, when the setting is defined, similar to the first image in the OP. I dont think this is a good idea since it would not be consistent with the way the documentation of ProjectSettings is done.

As a side note, the system works for ProjectSettings since each class has it's constructor called when you get the property list

[bojidar-bg]

... but there are so many other definitions, like ones defined in editor plugins which are never loaded, ...

Might be a good idea to move all the non-module settings there.

[EricEzaM]

Also, as a result of the EditorNode and related classes not being constructed, some project settings are actually left out of the documentation, such as editor/main_run_args which has it's GLOBAL_DEF in the EditorNode constructor, so when running the doctool it is never called.

@bojidar-bg interesting idea... So we just move all EDITOR_DEF calls into one central location, and they are always built/made/defined no matter what. We could also do this for GLOBAL_DEF (project settings), which would stop things like GLOBAL_DEF(application/run/main_scene", "") from appearing 3+ times in the code base. There should be one *_DEF and then only *_GET

So then if you wanted to make a new editor setting? Put it in the central location and used EDITOR_GET where you need it.

[paulloz]

Hey 👋
I just want to throw my two cents in because imho an aspect of this hasn't been discussed. There is still no way of populating tooltips for properties created on the fly.
A lot of plugins are actually written in GDScript and are using API methods to inject properties into the editor GUI (the list probably not exhaustive):

• EditorImportPlugin.get_import_options
• ProjectSettings.add_property_info
• EditorSettings.add_property_info
• Quite simply the export keyword in GDScript (which is adressed by Tooltips for exported variables godot#35716 I guess?)

Long story short, it feels a bit off having the ability to create entries in almost every part of the editor and still not having the possibility to give the end user information about them in their respective tooltips.

Sorry if that's not 100% exactly what this issue is about, there's already quite a lot of open issues about tooltips and after reading them, this one seemed the right one to comment on...

Cheers.

[Calinou]

Quite simply the export keyword in GDScript (which is adressed by godotengine/godot#35716 I guess?)

This is already implemented in master by godotengine/godot#41095. The pull request you linked aims to reimplement it for the 3.x branch.

[Calinou]

@EricEzaM You workaround seems to generate the documentation fine (thanks a lot 🙂). However, I get a segfault when --doctool . is done running:

WARNING: ObjectDB instances leaked at exit (run with --verbose for details).
     at: cleanup (core/object/object.cpp:1932)
[Thread 0x7fffea3d7640 (LWP 53440) exited]
ERROR: Resources still in use at exit (run with --verbose for details).
   at: clear (core/io/resource.cpp:427)

Thread 1 "godot.linuxbsd." received signal SIGSEGV, Segmentation fault.
OS::print_error (this=0x0, p_function=0x1c4de2d "unref", p_file=0x1cf7424 "core/string/string_name.cpp", p_line=94, 
    p_code=0x1d0b740 "BUG!", p_rationale=0x1dba76c "", p_type=Logger::ERR_ERROR) at core/os/os.cpp:109
109             if (!_stderr_enabled) {
(gdb) bt
#0  OS::print_error (this=0x0, p_function=0x1c4de2d "unref", p_file=0x1cf7424 "core/string/string_name.cpp", 
    p_line=94, p_code=0x1d0b740 "BUG!", p_rationale=0x1dba76c "", p_type=Logger::ERR_ERROR) at core/os/os.cpp:109
#1  0x0000000008f5f9d7 in _err_print_error (p_function=0x1c4de2d "unref", 
    p_file=0x1cf7424 "core/string/string_name.cpp", p_line=94, p_error=0x1d0b740 "BUG!", p_message=0x1dba76c "", 
    p_type=ERR_HANDLER_ERROR) at core/error/error_macros.cpp:77
#2  0x0000000008f5f98a in _err_print_error (p_function=0x1c4de2d "unref", 
    p_file=0x1cf7424 "core/string/string_name.cpp", p_line=94, p_error=0x1d0b740 "BUG!", p_type=ERR_HANDLER_ERROR)
    at core/error/error_macros.cpp:69
#3  0x0000000008f14ff7 in StringName::unref (this=0xbaf9220) at core/string/string_name.cpp:94
#4  0x0000000008f19f65 in StringName::~StringName (this=0xbaf9220) at core/string/string_name.cpp:378
#5  0x000000000679374f in EditorSettings::~EditorSettings (this=0xbaf90b0) at editor/editor_settings.cpp:1804
#6  0x00000000066aba25 in memdelete<EditorSettings> (p_class=0xbaf90b0) at ./core/os/memory.h:115
#7  0x00000000066ab9d6 in Ref<EditorSettings>::unref (this=0x9a030b8 <EditorSettings::singleton>)
    at ./core/object/reference.h:221
#8  0x00000000066ab975 in Ref<EditorSettings>::~Ref (this=0x9a030b8 <EditorSettings::singleton>)
    at ./core/object/reference.h:233
#9  0x00007ffff7a71237 in __run_exit_handlers () from /lib64/libc.so.6
#10 0x00007ffff7a713e0 in exit () from /lib64/libc.so.6
#11 0x00007ffff7a591e9 in __libc_start_main () from /lib64/libc.so.6
#12 0x0000000004969d2e in _start ()

(I had to use gdb as the built-in crash didn't work here.)

[cloa513]

The tooltips should appear when you click on a property or its value. The user is showing he probably wants it- it maybe should listed in the project settings as an option.