The main point of this feature is that it should be automatic: if a type does not allow being using with g_auto* then it is, ostensibly, a bug in the library providing the type. You don’t document functionality that is expected to work by default.
How does a newcomer know anything about a library? By reading the documentation and by reading other people’s code. We have this thing called “free and open source software” for a reason.
Aside from the fact that it is documented, and C examples tend to use g_auto, using the automatic cleanup isn’t required: things work perfectly well without them. The automatic cleanup is also non-portable: it does not work if you’re using the MSVC toolchain, for instance.
There’s no point in adding a note for every single type: if a type does not provide a G_DEFINE_AUTOPTR_CLEANUP_FUNC then file a bug against the library that provides the type, or, better yet, open a merge request with the fix.
Yes. Non GCC / CLang issue is always there. But, I’m not sure if that’s really an issue for normal GNOME developers. Anyone who wants to use GLib code with MSVC toolchain should should know better about the portability issues involved in doing such work.
I think we need to add the above note in the API documentation for g_autoptr() / g_auto() etc. That should have cleared things up.
E.g.: .... all glib objects support automatic cleanup, else it's a bug and ...