Avoid using class names when possible in class reference

[timothyqiu]

There are two cases where it's annoying to see a class name. Both when reading the documentation and when translating the class reference.

Use Class Name as a Pun

One typical example is the description related to theme items:

the constant of something
the [Color] of something
the icon of something
the [Font] of something
the font size of something
the [StyleBox] of something

• It breaks consistency between different theme types.
• It's unnecessary because we're talk about the general concept color, font, and stylebox here instead of a specific class.
• It makes localization hard because class names can't be translated.

Enum names also have this problem. e.g.:

Sets the right [enum TangentMode] for the point at [param index] to [param mode].
Sets the right tangent angle for the point at [param index] to [param tangent].

The TangentMode here is not necessary. It can be figured out from property type, parameter type, or method return type.

Sets the right tangent mode for the point at [param index] to [param mode].
Sets the right tangent angle for the point at [param index] to [param tangent].

2D / 3D Versions Differ at Class Names Only

For example, the description of CharacterBody3D.get_last_motion()

Returns the last motion applied to the [CharacterBody3D] during the last call to [method move_and_slide]. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement.

is the same as the description of CharacterBody2D.get_last_motion(), except for the class name.

Returns the last motion applied to the [CharacterBody2D] during the last call to [method move_and_slide]. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement.

This creates two unique entries to translate which is unnecessary duplication of work. Translators should phrase different versions similarly.

It's worse for shared descriptions between Vector2, Vector2i, Vector3, Vector3i, Vector4, and Vector4i.

It's better to use a generic term when possible, e.g.:

Returns the last motion applied to the body during the last call to [method move_and_slide]. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement.

[dalexeev]

I remember there was a proposal/comment about templates/includes in the class reference for snippets repeated in multiple places.

[Mickeon]

This creates two unique entries to translate which is unnecessary duplication of work. Translators should phrase different versions similarly.

As I have noticed this too, it is an occasional, on-going effort to standardize descriptions as much as possible:

• Fix differences between CPUParticles2D and CPUParticles3D documentation godot#104354
• Fix differences between RayCast2D and RayCast3D documentation godot#105048
• Fix differences between PhysicsDirectSpaceState2D/3D docs godot#105051
• Fix some differences between OpenXRInterface and XRHandTracker docs godot#105095

Unfortunately, this will never be truly possible without some sort of mechanism to copy-paste documentation snippets. Having to reference either 2D or 3D is sometimes inevitable.