I am new to glibmm and am looking at the documentation for Glib::TimeZone c++ class. There are a few places, eg,. Glib::TimeZone::create_utc() where it states:
"You should release the return value by calling g_time_zone_unref() when you are done with it."
This seems odd for a C++ class.
Looking in the source code for the destructor of Glib::TimeZone, g_time_zone_unref() is called there, so am I right in thinking that I should ignore the statement in the documentation?
It seems a lot of the documentation refers to glib rather than glibmm, as if it's been generated from the underlying glib docs. Is this so? Should I be taking all the docs with a pinch of salt?
I'm using glibmm-2.68
It is sort of explained in the source code: https://gitlab.gnome.org/GNOME/glibmm/-/blob/master/glib/src/timezone.hg#L54-61
// GTimeZone is refcounted, but Glib::TimeZone is not.
// GTimeZone is immutable. Therefore, there is no problem having several
// Glib::TimeZone instances wrap the same GTimeZone, and it's easier to use
// Glib::TimeZone without Glib::RefPtr.
_CLASS_BOXEDTYPE(TimeZone, GTimeZone, NONE, g_time_zone_ref, g_time_zone_unref, GLIBMM_API)
_IGNORE(g_time_zone_ref, g_time_zone_unref)
So g_time_zone_ref() and g_time_zone_unref() are called automatically by the C++ Glib::TimeZone class. You should not call them explicitly.
The source code also says create() is deprecated and you should use create_identifier() instead. The difference is that create() returns the UTC zone if parsing failed, which makes it impossible to know if parsing failed, while create_identifier() returns null on error.
Why does the online documentation mention g_time_zone_unref()? Because it is auto-generated from the C documentation and the generator is not smart enough. An object lesson about the perils of generated documentation.