Add `<available-platform>` element in class reference XML

timothyqiu commented 1 month ago

Describe the project you are working on

Translating class reference.

Describe the problem or limitation you are having in your project

Similar notes about available platform are scattered in different places.

Their original wording may be different which is unnecessary. For example, we have:

This method is currently only implemented on macOS. This method is only implemented on macOS. This method is implemented only on macOS. Only implemented on macOS.
Because they are scatterred in different places, it's hard to be translate consistently.

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

Use a dedicated element for this kind of message.

Instead of plain text:

<description>
    Some description.
    [b]Note:[/b] This method is only impleted on macOS.
</description>

Use:

<description>
    Some description.
</description>
<available-platform name="macOS" />

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

All <available-platform> names are used to generate a list (instead of a sentence) at the end of the description text.

<available-platform name="Android" />
<available-platform name="iOS" />
<available-platform name="macOS" />

Generates:

Available on: Android, iOS, macOS

This also makes it easier if someone wants to use icons instead of texts to represent this information, or wants to generate a platform specific version of documentation.

Some existing notes contain additional description about general behavior:

<description>
    Some description about transparency.
    [b]Note:[/b] Transparency support is implemented on Linux (X11/Wayland), macOS, and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities.
</description>

The general part can be kept as-is:

<description>
    Some description about transparency.
    [b]Note:[/b] Transparency support availability might vary depending on GPU driver, display manager, and compositor capabilities.
</description>
<available-platform name="Linux (X11/Wayland)" />
<available-platform name="macOS" />
<available-platform name="Windows" />

A good thing about using a separate element is that name can be enumerated. Unknown names can be found by the XML validator.

If that's not a requirement, making it a comma-separated string attribute on method / member elements is also an option.

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

No. It's about class reference XML.

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

Same as above.

RedMser commented 1 month ago

I'm not sure about it being a mixed-content XML element, it would certainly be easier to parse as either a XML attribute or (one or multiple) custom BBCode-style tag like [meta available-platforms="..."]

XML schema validation could be replaced with custom validation logic like we already do for checking valid [param] names etc.

timothyqiu commented 1 month ago

I'm not sure about it being a mixed-content XML element, it would certainly be easier to parse as either a XML attribute or (one or multiple) custom BBCode-style tag like [meta available-platforms="..."]

Mixed-content element is difficult to parse does make sense :+1:

Updated the proposal. Now <available-platform> is at the same level as <description>.

RedMser commented 1 month ago

Note that this won't work for members, since they do not have a <description> element (this is also why keywords were made an attribute instead of element). Not sure how common platform-specific members are, though. ProjectSettings come to mind...

raulsntos commented 1 month ago

Somewhat related proposal about adding metadata to APIs:

https://github.com/godotengine/godot-proposals/issues/2550

From the .NET/C# perspective, I'd like to know which APIs are only implemented on certain platforms so we can use the appropriate C# attributes. For example:

[SupportedOSPlatform("linux")]
public void LinuxOnlyApi() { }

[SupportedOSPlatform("windows")]
[SupportedOSPlatform("ios14.0")]
public void SupportedOnWindowsAndIos14() { }

[UnsupportedOSPlatform("android")]
public void DoesNotWorkOnAndroid() { }

As you can see, these attributes can also specify the platform's version. And the supported platforms can be specified in a inclusive or exclusive way (e.g.: this API is supported only in these platforms - vs - this API is supported everywhere except for these platforms).

I think it's fine for this information to be in DocData instead of ClassDB (that's how deprecated and experimental work already), but ideally the names of the platforms would match the OS name used in their respective EditorExportPlatform implementations (i.e.: Linux instead of Linux (X11/Wayland)), that would make it easier for us to parse (and convert the name if necessary to the name required by the C# attribute).

From the perspective of GDExtensions, this would need to be surfaced in the dumped extension_api.json, so it may be better for this to be in ClassDB.

Calinou commented 1 month ago

Why not a list of comma-separated feature tags as an optional attribute of the method/property, like we do for keywords already? For example, features="windows, macos".

This can also be used to denote properties/methods that are only effective in the editor or in debug builds.

timothyqiu commented 1 month ago

Why not a list of comma-separated feature tags as an optional attribute of the method/property, like we do for keywords already? For example, features="windows, macos".

As explained in OP, valid platform names can be defined in XSD and checked by an XML validator.

It's also future-proof (not included in this proposal, but could be), e.g.:

<available-platform name="iOS" minimum_version="14.0" />
<available-platform name="Windows">
    [param key_callback] is ignored.
</available-platform>

Available on: iOS 14.0+, Windows

Windows: `key_callback` is ignored.

godotengine / godot-proposals