Separate classes into groups in the Godot API documentation

[zrckr]

Describe the project you are working on

N/A - Reading the GDScript and API documentation.

Describe the problem or limitation you are having in your project

The Godot API documentation describes all the classes that are available to the GDScript or C# developer. However, these classes are not separated by namespaces or groups that would indicate which domain the class belongs to. For example, there are classes that responsible for implementing VisualScript, physics, servers, collections etc.

Some classes have prefixes in their names that denote their belonging to a domain. Nevertheless, all the classes in the API docs are essentially laid out in one big long list of classes, which can be confusing to a developer.

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

Separating classes by groups can help to:

• Categorize classes according to their field of application.
• Generate actual namespaces in C# (currenty, most of classes are laid out in Godot namespace).
• Speeds up documentation searches, in case the developer is looking for a specific class to work with.

There are two ways to separating classes:

Option 1. Using folders like in the engine repository.

The source code is quite conveniently divided into folders, each responsible for a different area. For example, classes for working with the scene are in `scene` folder, with the editor - in `editor` folder, various modules - in the appropriate folders in `modules` folder.

Here is an example:

• The class AABB along the path docs/core/math/AABB.xml will belong to the group core.math.
• The class Node3D along the path docs/scene/3d/Node3D.xml will belong to group scene.3d.

This will require moving the class documentation files to similar folders in the godot repository.

Option 2. Explicitly specify the group via a tag in the XML documentation files.

Since this proposal only refers to documentation, it makes sense to add a special `group` tag to indicate which group this class belongs to.

Here is an example of a description of an AABB class that belongs to the group Core.Math:

<?xml version="1.0" encoding="UTF-8" ?>
<class name="AABB">
	<brief_description>
		Axis-Aligned Bounding Box.
	</brief_description>
	<groups>
                <group>Core</group>
                <group>Math</group>
        </groups>
...
</class>

With this implementation, generating namespaces for the C# API is a fairly trivial task.
This would require changing every XML file in the godot repository.

In both cases, we also need to change (or refine) the scripts that automatically generate the API from the XML files.

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

We will have a separation of classes into groups, like in:

Unigine API documentation

Unity API documentation

In the case of C# we will get this following code:

using Godot.Collections;

namespace Godot.Math {
     public class AABB {
     }
}

namespace Godot.Scene {
     public class Node : Godot.Core.Object {
     }
}

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

No. This requires changing files in the documentation folder.

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

This is about the core documentation.

[Calinou]

Godot had manually defined categories for nodes, but they were eventually removed since they were unused: godotengine/godot#18711

Generate actual namespaces in C# (currenty, most of classes are laid out in Godot namespace).

Godot's C++ codebase doesn't use namespaces much (if at all), so this wouldn't be feasible yet.

[YuriSizov]

Speeds up documentation searches, in case the developer is looking for a specific class to work with.

That's not necessarily true. Currently, looking up any Godot type in the list can be done alphabetically, same as a book index page. Grouping would require the reader to assume (or guess) a category before looking up by the name. It's one thing when grouping comes naturally and/or the API footprint is small, but Godot has a lot of classes.

On the other hand, I was just about look something up in the online docs, and I know that the thing I am looking for is a resource. With that prior knowledge it would be faster to find relevant information. So maybe we can do that, split the class reference not by usage, but by inheritance and only for the top-level types (Node, Resource, everything else/Object).

[aaronfranke]

I think this is a great idea! I don't think we need to manually define categories in each type's code, we can just do some checks based on class inheritance and class names.

Here's a proof-of-concept for this: aaronfranke/godot@41512f7

This results in the following folder structure: https://github.com/aaronfranke/godot/tree/doc-folders/doc/classes

The bulk of the logic is in the ClassDB::get_class_category method, but I also needed to change some other parts of the codebase to handle loading documentation from subfolders. Still, it's under 100 lines of code added.

[YuriSizov]

I don't think we need to manually define categories in each type's code

You kinda do the same, just with less manual labor. But maintenance is going to be a pain with that.

But this is cool!

[me2beats]

Would be handy to have 2 views, the old one and the categorized one
The user could switch between them

[dalexeev]

Related:

• Add filter buttons to core/custom classes in the Search Help dialog #4285

[Calinou]

We discussed this proposal in a meeting and agreed that readding categories to nodes/resources could be useful. However, it's not clear what kind of separation would be the most productive. It was suggested that classes are separated in a way similar to contributor teams.

[YuriSizov]

Since we've discussed that it may be good to have some kind of basic grouping still, I've experimented with this idea a bit, and here're two PRs:

godotengine/godot#63497
godotengine/godot-docs#5990

This splits online docs into 4 main groups: Nodes, Resources, other classes, and global scopes.

[Splizard]

@YuriSizov I don't think inheritance-based grouping would be very effective, you can already start with the Object class and explore children classes very effectively.

As @Calinou mentioned, it makes more sense to structure classes around team functional boundaries.
https://godotengine.org/teams

• core
• gui
• editor
• scripting
• platforms/system
• animation
• audio
• import/assets
• networking
• physics
• rendering
• xr

As mentioned in my proposal, I'm willing to make an attempt on this. Let me know if I you’d like me to draft up a PR or if this is something yourself and/or other contributors want to look at instead.

[YuriSizov]

@Splizard I'm not proposing this as a final solution, but it still saves time when navigating the documentation. A proper solution would require some kind of introduction of tags for classes, so that they can be marked as relevant to various subjects, but that's a ton of work that is going to take a lot of time to finalize and make sure everyone is happy.

You are free to work on this if you wish. There was an old system for something similar that was ultimately unused and scrapped, but may be of interest to you. This is unrelated to the base type grouping that I've added, which only aims to make the list a bit more organized without impacting discoverability.

Edit: Oh, and also see godotengine/godot#63086 for its discussion and resolution. It's a bit fresher than Calinou's comment up there.

---

Personally, I wouldn't want complex grouping because it makes it harder to look up stuff if you know the name. I don't think that your use case of opening a category and learning nodes related to it is a part of a normal dev process. To me the class reference is something you refer to when you face a problem and get a suggestion for a solution. Mindlessly going through the docs sometimes helps, but is not very practical.