GNOME Bugzilla – Bug 317679
GRelation field type not documented
Last modified: 2011-02-18 16:14:20 UTC
The docs for GRelation never specify what the type of data items inserted into the relation are. This is rather important, since g_relation_insert is a varargs function, so for example inserting doubles produces buggy code but does not trigger any compiler warnings of any sort. The docs for g_relation_insert say: ... : the fields of the record to add. This must match the number of fields in the GRelation. that should become: ... : the fields of the record to add. This must match the number of fields in the GRelation, and be of type gpointer or gconstpointer. or something along these lines...
Careful, if we document GRelation too well, someone might start using it...
:). I was thinking about extending it to support more than two fields the other day. I wish there were more levels of deprecatedness. There's no way for one to know GMemChunks are bad through reading docs. They still say "Memory chunks provide an efficient way to allocate equal-sized pieces of memory"... If GRelation is an old mistake and doesn't belong to GLib if it was designed today, then I like to see it in the docs. One more thing I would like to see in the docs is time-order of the implementations, plus some informal measure of heaviness. For example, it's not totally obvious for a new user that g_list_append is not O(1). Of course if you wait and think about you, you definitely find out GList is not keeping track of the tail, but that's more a design/implementation issue. Most people think of doubly-linked lists as O(1)-append.
I don't think there is anything *wrong* with GRelation (as far as we know), the mistake in adding it was mostly that it hasn't proved useful to many people (any people?).
Behdad, feel free to polish the GRelation docs if you want.
2006-01-31 Behdad Esfahbod <behdad@gnome.org> * docs/reference/glib/tmpl/relations.sgml (g_relation_insert): Specify the type of varargs arguments. (bug #317679)