Documentation Improvement for GValue and Boxed types

Sorry for the slow reply, but thank you for spending the time to diagnose the issues you’ve had with the documentation and write them all up. It’s not often we get enthusiastic feedback like this. :slightly_smiling_face:

Searching for GBoxed does bring up the GBoxedCopyFunc and GBoxedFreeFunc documentation for me, which are on the right page.

I think the fix here is to add full-text search to Devhelp (currently it only searches page titles and possibly keywords). Please file an issue against Devhelp about that, if one doesn’t exist already.

A shorter-term fix might be to add an additional indexterm element to the ‘Boxed Types’ docbook page, although that’s a tentative fix because I’m not sure how to do that in gtk-doc (which is what GLib uses to generate its documentation) and I’m not sure whether Devhelp searches the index terms.

Merge requests welcome. :slightly_smiling_face:

The first page is the one which describes GValue, the second is the tediously long list of all the different types it supports. I suspect they are separate because a combined page would be too long to usefully be able to find anything in.

I suspect the fix for this in the long term is to use something with a less linear structure than gtk-doc for documenting GLib.

In the meantime, your suggestion of adding ‘See also’ links would help; please feel free to open a merge request. :slightly_smiling_face:

Yes, g_value_unset() should definitely be mentioned in the GValue ‘description’ section. Merge request welcome for that.

Renaming g_value_unset(), or even providing a wrapper for it with a new name, is not going to happen, as it would be incredibly disruptive to existing code (by triggering a lot of deprecation warnings which maintainers have to fix, without the new function providing any benefit to them).

unset is a more consistently used term within the GNOME/GLib ecosystem than uninit, so once people have learned that it means to clear the internal data from a structure without freeing the structure itself, that knowledge can safely be applied consistently to other GLib-style APIs.

It’s safest to assume that an unset() call is always needed, regardless of the type. One of the purposes of GValue is to be able to dynamically marshal different types through the same code, so the code can’t necessarily assume that a GValue will have a certain type and hence will/will not need unset() called on it.

If the type information was known at compile time, there would be little point in using GValue — the code might as well use the underlying wrapped C type.

I think you might be misunderstanding here. The function naming is consistent. set functions set the GValue to a copy of their argument. In the case of non-pointer types (integers, booleans), this is a copy-by-value. In the case of pointer types, this is a copy by whatever copy function is relevant to the type (g_strdup() for strings, g_object_ref() for GObjects, etc.). set_pointer treats the pointer as an opaque value; if you need more specialised handling for a particular pointer type, it must be boxed using GBoxed, which exposes the ref/unref functions for that type to the runtime type system.

take functions set the GValue to their argument without copying, on the assumption that ‘ownership’ of the argument has been passed to the GValue.

Merge request welcome. :slightly_smiling_face:

3 Likes