Is there a way to know whether a particular type supports automatic cleanup ?
i.e. implements "G_DEFINE_AUTOPTR_CLEANUP_FUNC" / "G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC" / … / etc )
without looking into the code ( eg. "gio-autocleanups.h", "glib-autocleanups.h" etc ) ?
E.g. Maybe a table in "devhelp", similar to those in "man" pages
| Interface | Attribute | Value |
|---|---|---|
| malloc(), free(), calloc(), realloc() | Thread safety | MT‐Safe |
Cheers!
This would be more a feature request for gi-docgen or gtk-doc.
I don’t know if the information is available in the GObject Introspection files (for gi-docgen to consume that information). If it’s not the case, that could be a feature request for GI as well, then.
No. The only way to know programmatically if a type implements automatic cleanup is to do a version check on the library, if you know which version introduced automatic cleanup.
For object types, anything using G_DECLARE macros in the header automatically provides cleanup functions.
The automatic cleanup is C only, and it leaves no trace in the introspection data—nor would I expect it to.
If it’s not in the introspection data, then there is no possibility of automatic documentation.
So, a manual update like it’s done for the "Since: version" in header files ?
Since tags are bound to types and symbols; adding a G_DEFINE_AUTOPTR_CLEANUP_FUNC does not have any symbol.
In general, we don’t document if a type can be used with g_auto and friends.
We can just add a tag around the actual object e.g GBytes ( rather than G_DEFINE_AUTOPTR_CLEANUP_FUNC ) that is supports g_autoptr … etc
Even if that is not possible we can just manually add "text" to API documentation for the type ( typically typdef ) that this type supports automatic cleanup via "auto_*" functions.
Having done all the hard work of supporting this feature, and not providing this info in the API documentation is not very useful.
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 newbie who uses a GLib type (e.g. "GBytes") from the API documentation, know anything about "g_auto" family of functions ?
The user might write a whole program without knowing anything about "g_auto*" feature, as it not presented anywhere explicitly.
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.
Thanks for the link. But, I don’t see "Automatic Cleanup" section in my "Devhelp" app.
Are these 2 different documentations for GLib ?
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 ...
This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.
