Add introduction date of classes and methods in the documentation

[adamscott]

Describe the project you are working on

I'm working on the Godot Engine 4.4 release page.

Describe the problem or limitation you are having in your project

There's a feature that doesn't seem to have been introduced in the Godot 4.4 blog posts, and I want to make sure that this feature is actually new since 4.4 without asking everyone about this, or to manually check merged PRs.

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

We should add the introduction date of a feature in the documentation. This would make people more knowledgeable since when a feature exists.

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

It would work a lot like Emacs does. Here's an example of the pixel-scroll-precision-mode symbol documentation in Emacs 29.4 mentioning since when this mode exists. (I highlighted the line in yellow.)

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

This is core to the class documentation.

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

This is core to the class documentation.

[Calinou]

• Related to Add <available-platform> element in class reference XML #9762.

This was requested elsewhere already (on a per-property basis), but I can't find it right now.

[Ivorforce]

This can be very helpful when you swap between versions a lot, and especially if the same version of the documentation is often used as reference for multiple versions at once.

This kind of feature is also available in the NumPy docs (example) (and, I'm sure, in many others too).
For Godot, I see it as somewhat less useful since you generally access docs in-editor, or the fitting online docs for your version (because the ABI does still change a lot). But it would definitely still be nice information to have easily accessible.

[adamscott]

This would be especially useful for tool developers.

[tetrapod00]

For historical context, there was a version attribute, but it marked the overall engine version, not the introduction of a specific feature: godotengine/godot#79092

[Calinou]

Regarding how to introduce this to the class reference, how should we proceed? I assume this will take the form of an optional since attribute on all members (classes, properties, methods, signals, constants, theme items, …).

For existing members, we will probably have to label all of them with the first version this feature is introduced in (e.g. since="4.5"), unless we go through the effort of identifying the older ones and labeling them as such (e.g. since="4.0").

Once this is done, --doctool would add since="major.minor" to newly added members according to the current engine version from version.h. It wouldn't change the value if it's already set though.

Also, how should user-provided scripts provide this since attribute, if we decide to make it possible? Would since still refer to an engine version or the project version instead (e.g. the plugin's version, for editor plugins)?

[Ivorforce]

For existing members, we will probably have to label all of them with the first version this feature is introduced in

I think it might be better not to label those at all. The doctor should be capable of adding the "since" attribute only if adding a new xml item, but not for those that already exist.