Add keywords for easier searching of methods/properties/… in the class reference

[Calinou]

Describe the project you are working on

The Godot editor 🙂

Describe the problem or limitation you are having in your project

Finding properties/methods in the class reference can be difficult if you don't know the exact name of the property/method. See #5077 where this issue was encountered.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Add keywords for easier searching of methods/properties/… in the class reference.

This is something I originally proposed in godotengine/godot#29286 (comment) and godotengine/godot#29286, but it seems I forgot to open a proposal about it until now.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

• Add an optional keywords="keyword1, keyword2, ..." attribute on property/method/signal/constant/theme_item/enum/annotation tags. This attribute won't be generated by --doctool, so it'll be up for contributors to add it where needed. (For consistency, tt should always be added as the last attribute.)
  • The keywords tag is probably not relevant for constructors and operators.
• Modify --doctool to preserve the keywords attribute on relevant tags.
• Update the XML schema to allow the optional presence of a keywords attribute on relevant tag.

The online class reference may be able to benefit from this by collecting all keyword aliases for each class, then throwing them all under a <meta keywords="..."> tag using the following reStructuredText at the top:

.. meta::
    :keywords: keyword1, keyword2, ...

This keywords meta tag is ignored by search engines like Google, but the internal search bar will make use of them.

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

No.

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

This is about improving documentation usability.

[Zireael07]

+100, often I try to find a function without remembering the exact name, and the search will find everything BUT the thing I'm looking for :/

[Mickeon]

Let's think of some examples. What would be among the most common keywords that one could use? And what other cases other than the ones proposed would keywords be used on?

[Zireael07]

"mouse click" or some similar to InputEventMouseButton
'store string with len/length" for "store_pascal_string"
"ragdoll" for "physical bone"
"trigger" for "area2d/area3d" (this is a very common name in many other engines)
"ascii string" for "get_string_from_ascii" in PoolByteArray

If I remember some others, I'll note them down.

[Mickeon]

I just thought of another usage for keywords. Sometimes, the renames of Godot 4 are so difficult to re-find or recognise, that it may be good to include their 3.x names as keywords, too.

[YuriSizov]

• Add an optional keywords="keyword1, keyword2, ..." attribute on property/method/signal/constant/theme_item/enum/annotation tags.

If we go with this proposal, I'd change that bit. Changing the XML structure by hand can be annoying. I'd probably go with a new bbcode tag, [keywords], that would be stripped from the displayed text and parsed for its contents to extract the keywords.

Can be placed in any description. ...which can be a problem if there is no description field for something. Hmm...

[Mickeon]

That sounds pretty clever, actually. Is there a problem in handling those cases without description as the exception to the norm?

[YuriSizov]

Is there a problem in handling those cases without description as the exception to the norm?

No problem other than adding support for descriptions just to allow keywords.

Actually, the only thing that doesn't have a description which I can remember are the class members that override their parent. So maybe it's not a problem at all.

[aXu-AP]

I think this could extend to add node dialog and script editor as well. Not everybody knows to press F1. In script editor, suggestions based on keywords should be ranked lower not to clog more literal finds.

Here's a few more keyword suggestions:
queue_free & free: delete, remove, kill, die
instantiate, new: add, create, make
Plus whatever Unity, Unreal and Gamemaker calls their equivalent components, functions etc.

[hilfazer]

begins_with: starts_with

That's based on a real use case. I almost started implementing my own function because i was looking for starts_with.

[aXu-AP]

Note: keywords should be implemented in such a way that they can be translated to other languages. This would boost usability a lot for somebody who doesn't know english well, as even with fully translated editor node names and scripting api are in english

[Mickeon]

If they are included within the documentation's xml file there would be no issue then. (As part of the description)