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