Documentation example for nullable out parameters is wrong
The annotations docs provide an example mylib_hash_table_iter_next() to demonstrate the difference between (nullable) and (optional) for (out) parameters.
But this is a bad example because, and as explained earlier in the docs, A number of things are nullable by convention, including gpointer
parameters (since 10cb665f). And this example uses gpointer
-typed pointers.
Indeed, this is reflected in the documentation of g_hash_table_iter_next()
, which states, for the key
parameter The argument can be set to NULL by the method. despite it not being explicitly annotated as nullable.
...
/** * mylib_hash_table_iter_next: * @iter: an initialized #MylibHashTableIter * @key: (out) (optional): a location to store the key * @value: (out) (optional) (nullable): a location to store the value * * [...] * * Returns: %FALSE if the end of the #MylibHashTable has been reached. */ gboolean mylib_hash_table_iter_next (MylibHashTableIter *iter, gpointer *key, gpointer *value); /* this is valid because value and key have (optional) */ mylib_hash_table_iter_next (iter, NULL, NULL); gpointer key, value; mylib_hash_table_iter_next (iter, &key, &value); if (value == NULL) /* this is valid because value has (nullable) */ if (key == NULL) /* this is NOT VALID because key does not have (nullable) */
Edited by António Fernandes