Update documentation for DisplayServer::FEATURE_ICON

[sockeye-d]

The documentation got out of sync with what the Wayland server actually returns since #107096, so it should say

Display server supports changing the window icon (usually displayed in the top-left corner). [b]Windows, macOS, Linux (X11/Wayland)[/b]

Although, maybe it should be indicated that Wayland support is still spotty, and in the original PR it mentions only KWin supports it.

Closes #113874

[deralmas]

Although, maybe it should be indicated that Wayland support is still spotty, and in the original PR it mentions only KWin supports it.

Hi, I don't think that we should do this, as it would be unreliable info in a few ways.

This is a new standard extension that might be implemented by certain compositors, depending on whether they even have a concept of icons in the first place. Additionally, most distros take a while to ship the latest compositor versions anyways, so even once support is added, it will take some time to "percolate" down into common usage.

Perhaps we could specify that it depends on this specific extension though, so that users can check that themselves with tools like wayland-info. Previously I added startup warnings for some of this stuff (like decorations), but some people got even more confused, as they (understandably) thought that it was a bug.

FTR, we can't assume any specific extension to be there, that's why a lot of features might not work on certain compositors. That's just the nature of the Wayland ecosystem, and not too unlike to certain graphics drivers or GPUs missing certain extensions. This is definitely quite a different paradigm compared to previous software configurations, and something that I'm still looking into how to communicate effectively.

Out of date

[sockeye-d]

@deralmas How about

Display server supports changing the window icon (usually displayed in the top-left corner). [b]Windows, macOS, Linux (X11)[/b]
[b]Note:[/b] Use on Wayland requires the compositor to implement the [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#xdg_toplevel_icon_v1]xdg_toplevel_icon_v1[/url], which currently only KWin >6.4 supports.

to just add a little more specificity?

[akien-mga]

I wouldn't mention KWin explicitly, but instead link to https://wayland.app/protocols/xdg-toplevel-icon-v1#compositor-support for an evolving list of which compositors support the protocol.

[deralmas]

I agree with akien, again, mentioning specific stuff "at the time of writing" would still be inaccurate (different distro policies) and get outdated fast.

+1 on the idea of linking wayland.app, which is the de-facto standard documentation viewer for all protocols.

[sockeye-d]

Alright, how about

Display server supports changing the window icon (usually displayed in the top-left corner). [b]Windows, macOS, Linux (X11)[/b]
[b]Note:[/b] Use on Wayland requires the compositor to implement the [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#xdg_toplevel_icon_v1]xdg_toplevel_icon_v1[/url]. Not all compositors do: see [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#compositor-support]xdg_toplevel_icon_v1#compositor-support[/url] for more info.

[deralmas]

I think that the general structure you've proposed is good, for now. Regarding the exact grammar, I'd change "requires... to implement the xdg_toplevel_icon_v1." to "requires... to implement the xdg_toplevel_icon_v1 protocol.". ("protocol" is Wayland parlance for "extension")

That said, IMO, in the long term we should probably find a good way to communicate that "not all compositors implement x protocol" is implicit, especially if we plan to document the relevant protocol(s) for each feature. Perhaps we could eventually make a "Wayland support" doc page and link it?

[sockeye-d]

Alright, the documentation file's been updated

[akien-mga]

Suggested change

	[b]Note:[/b] Use on Wayland requires the compositor to implement the [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#xdg_toplevel_icon_v1]xdg_toplevel_icon_v1[/url] protocol, which not all compositors do. See [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#compositor-support]xdg_toplevel_icon_v1#compositor-support[/url] for more info on individual compositor support.
	[b]Note:[/b] Use on Wayland requires the compositor to implement the [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#xdg_toplevel_icon_v1]xdg_toplevel_icon_v1[/url] protocol, which not all compositors do. See [url=https://wayland.app/protocols/xdg-toplevel-icon-v1#compositor-support]xdg_toplevel_icon_v1#compositor-support[/url] for more information on individual compositor support.

[Repiteo]

Thanks!