My impression is that some entries in the GIR files are just wrong

Some days ago I noticed that a few of the gobject-introspection generated functions for the Nim bindings are wrong.

Concerned are only a few functions with parameters of type NULL-terminated array of string.

Well of course I thought that I may do something wrong in the gintro package, so I spent whole evening yesterday and a few hours today on this issue. But now I get the impression that the GIR files just contain insufficient entries like

<function name="strv_length" c:identifier="g_strv_length" version="2.6">
<doc xml:space="preserve">Returns the length of the given %NULL-terminated
string array @str_array. @str_array must not be %NULL.</doc>
<return-value transfer-ownership="none">
<doc xml:space="preserve">length of @str_array.</doc>
<type name="guint" c:type="guint"/>
<parameter name="str_array" transfer-ownership="none">
<doc xml:space="preserve">a %NULL-terminated array of strings</doc>
<type name="utf8" c:type="gchar**"/>

From the doc comment we learn that parameter str_array is an NULL-terminated array of strings, which matches the c:type=“gchar**”. But type name=“utf8” is the only info available for introspection, so for the bindings I have that type is utf8, and that it is a pointer. But Of course that is not correct, as we know that is a NULL-terminated array of strings. I think there is really no way to get the correct information from gobject-introspection – maybe there are no correct annotations in source code?

Luckily these issues are rare, less than 100 I think. Most functions are correctly annotated as array type when a parameter is an NULL-terminated array of strings.

Maybe looking at the C source codes support my assumption:

 * g_strv_length:
 * @str_array: a %NULL-terminated array of strings
 * Returns the length of the given %NULL-terminated
 * string array @str_array. @str_array must not be %NULL.
 * Returns: length of @str_array.
 * Since: 2.6
g_strv_length (gchar **str_array)
  guint i = 0;

  g_return_val_if_fail (str_array != NULL, 0);

  while (str_array[i])

  return i;

 * gtk_selection_data_set_uris:
 * @selection_data: a #GtkSelectionData
 * @uris: (array zero-terminated=1): a %NULL-terminated array of
 *     strings holding URIs
 * Sets the contents of the selection from a list of URIs.
 * The string is converted to the form determined by
 * @selection_data->target.
 * Returns: %TRUE if the selection was successfully set,
 *   otherwise %FALSE.
gtk_selection_data_set_uris (GtkSelectionData  *selection_data,
		         gchar            **uris)

For gtk_selection_data_set_uris(), which is an example for the majority of functions which gives me fully correct bindings, there is @uris: (array zero-terminated=1): which is missing for g_strv_length()

That is not completely uncommon unfortunately. Not all API have been annotated since the introduction of GObject Introspetion, resulting in some errors where the defaults are incorrect. Quite often, this renders the API completely unusable and the fix is to simply add the missing annotation so that the API will become usable with the next update.

I think that the GStrv functions are quite special though. As it is really just an array of strings (i.e. zero-terminated gchar**) it should be handled in the same way as any other array by the binding. That is, it should be translated to a native array type. As a result the g_str*v and g_strv_ functions will not have any use for bindings and should likely be marked as (skip) so that they do not even appear in the introspection data.

Yes indeed no one of the few Nim GTK users has reported a wrong glue function until now. I have noted a bug myself some days ago, when I had to use g_strfreev() for binding gtk functions which returns a null terminated string array to Nim’s native data type. And then I saw some similar bugs, so my first guess was that there may be a bug in my bindings generator for some special corner cases.

The wrong annotated gtk functions should be fixed or marked as skip. I think I will report the issue then to gnome bugzilla – ebassi told me recently that gobject-introspection is still alive, so reporting issues may be not fully wasted time.

The annotations for GLib are maintained inside GLib itself, so it has nothing to do with gobject-introspection.

If you find that the annotations of an API are incorrect, you should always file a bug against the project that exposes that API.

Yes, it seems that glib has the most wrong candidates:


I will try to file a bug.

One question:

The GIR files like /usr/share/gir-1.0/Gtk-3.0.gir also contain some comments about the functions, may it be possible to read out these comments with gobject-introspection API?

GLib is a C utility library; at the lowest level, C API is not really introspectable.

The g_option_* ones already have an open issue.

No. The documentation is not stored inside the typelib binary data, to avoid bloating its size, and it’s only available by parsing the XML.

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.