Let's fix the categories together :)

[reduz]

One complaint I hear often about Godot is that it's not possible to sort classes by cateogories, to learn better where each belongs.

Godot has a system of tagging a class with a category:

But this is not really used well and not taken advantage of, I filled those 10 years ago and have not been updated since.

I think we should define categories properly, so it's possible to add options to sort classes by them in the help and documentation. Anyone up for this?

[akien-mga]

What should the categories be, though? If "Nodes" is meant to be a category for all nodes, then it might be best to just infer this in DocData based on the inheritance tree (all classes inheriting Node are of category "Nodes") than specifying it manually everywhere.

But at the same time I'm not sure that a "Nodes" category is really useful.

I remember that at some point we thought about various categories with @bojidar-bg to split the then-monolithic classref XML in separate components, along the lines of Node2D, Spatial, Control, etc.

[Zylann]

A category can, but doesn't always map to what a class inherits though. It's often possible to infer it with nodes due to their heavy use of inheritance, but less with resources. There is also no category for animation, network or editor-sepcific classes (the latter is useful when making plugins).

2D and 3D is also very broad, if you unfold Spatial or Node2D you have a plethora of nodes to choose from, so categories seem to make sense to organize them (and they could need support for subcategories).

And on the opposite, dialogs are a bit extreme:

[neikeq]

I was looking into categories when I started working with the C# bindings but, as you mention, they aren't used correctly. My intention was to put the generated classes in their respective namespace depending of their category.
Some examples: Resources, Navigation, Audio, Physics, Animation, GUI, Networking, IO, Threading (maybe not... what could go in other than Thread?).

[Zylann]

@neikeq Mutex?

[neikeq]

@neikeq Mutex?

Indeed. Semaphore as well.

[neikeq]

Any updates on this? I plan to divide the C# bindings into namespaces (and maybe into assemblies) for 4.0 and it would be great to do this automatically from categories?
I don't know if the idea @reduz has for categories would be translatable to namespaces, so it would be great if we could elaborate more about this.

[neikeq]

@reduz Later this month I will work on namespaces for C# and it would be great if we could use categories for that. Can we discuss what you have in mind?
IMO the categories itself should be named in a way they're actually useful, like the examples I've shown above (there would probably be many more categories).
The example in your screenshot of how they're being used right now is exactly what I would not like, as not only "Nodes" is not very useful but you already can determine that by checking if it inherits Node.

[akien-mga]

Here's the list of categories currently used:

$ rg --sort path 'OBJ_CATEGORY'
core/io/ip.h
41:     OBJ_CATEGORY("Networking");

core/io/resource.h
51:     OBJ_CATEGORY("Resources");

core/io/stream_peer.h
42:     OBJ_CATEGORY("Networking");

core/io/stream_peer_tcp.h
41:     OBJ_CATEGORY("Networking");

core/object/object.h
457:#define OBJ_CATEGORY(m_category)                                        \

core/os/main_loop.h
41:     OBJ_CATEGORY("Main Loop");

scene/3d/collision_shape_3d.h
40:     OBJ_CATEGORY("3D Physics Nodes");

scene/3d/light_3d.h
38:     OBJ_CATEGORY("3D Light Nodes");

scene/3d/node_3d.h
53:     OBJ_CATEGORY("3D");

scene/3d/visual_instance_3d.h
38:     OBJ_CATEGORY("3D Visual Nodes");

scene/animation/animation_player.h
65:     OBJ_CATEGORY("Animation Nodes");

scene/gui/control.h
47:     OBJ_CATEGORY("GUI Nodes");

scene/main/node.h
46:     OBJ_CATEGORY("Nodes");

I'm not even sure where this information is used. Since nothing really happened following to this issue, maybe the best right now would be to get rid of OBJ_CATEGORY. And if/when we figure out a proper way to categorize nodes and make use of this information, we can add it back.