Missing nullable GIR annotations and property documentation
The gtk-doc comments are missing mentions of nullable properties, and many parameters (and all properties) are missing nullable GObject instrospection annotations.
First, properties. In most cases, the set function for these properties allows null (and is annotated), but the get and dup functions do not mention the parameter's nullability and it is not annotated in GIR. The property itself (in the properties section) does not mention nullability or have GIR annotation either. Here are the instances I found of this case (I only found these using the documentation, so if there are nullable parameters that aren't explicitly called out, I haven't found them):
ESource.parent
ESource.uid
ESourceAuthentication.user
ESourceAuthentication.connectable
ESourceAuthentication.host
ESourceAuthentication.method
ESourceBackend.backend-name
ESourceSelectable.color
ESourceCollection.identity
ESourceGoa.account_id
ESourceGoa.calendar_url
ESourceGoa.contacts_url
ESourceMailComposition.drafts-folder
ESourceMailComposition.templates-folder
ESourceMailIdentity.address
ESourceMailIdentity.name
ESourceMailIdentity.organization
ESourceMailIdentity.reply-to
ESourceMailSignature.mime-type
ESourceMailSubmission.sent-folder
ESourceMailSubmission.transport-uid
ESourceOpenPGP.key-id
ESourceOpenPGP.signing-algorithm
ESourceResource.identity
ESourceSMIME.encryption-certificate
ESourceSMIME.signing-algorithm
ESourceSMIME.signing-certificate
ESourceWebdav.display-name
ESourceWebdav.email-address
ESourceWebdav.resource-path
ESourceWebdav.resource-query
ESourceWebdav.display-name
ESourceWebdav.ssl-trust
This also applies to function parameters, where it may be documented that the parameters can be null but this isn't in GIR.
- The
error
andcancellable
parameters in most functions (which are also lacking out annotations) -
e_source_ref_dbus_object
return -
e_source_set_parent
return -
e_source_new_with_uid
return -
e_source_new
return -
e_source_to_string
return -
e_source_registry_new_sync
ande_source_registry_new_finish
return -
e_source_registry_ref_source
return -
e_source_registry_list_sources
extension-name
parameter -
e_source_registry_find_extension
return -
e_source_registry_ref_default_mail_identity
return -
e_source_registry_ref_default_for_extension_name
return -
e_source_alarms_get_last_notified
return -
e_client_error_create
custom_msg
parameter -
e_flag_timed_wait
abs_time
parameter - Some parameters in
e_time_parse_date_and_time_ex
ande_time_parse_date_ex
(I don't understand what they do, so I can't tell what is nullable) -
e_util_strdup_strip
return -
e_util_strstrcase
return -
e_util_utf8_strstrcase
return -
e_util_utf8_strstrcasedecomp
return -
e_util_utf8_remove_accents
str
parameter -
e_util_utf8_make_valid
str
parameter -
e_util_utf8_data_make_valid
data
parameter -
e_util_utf8_normalize
return -
e_util_ensure_gdbus_string
str
parameter -
e_filename_mkdir_encoded
filename
parameter and return -
e_async_closure_callback
object
parameter -
e_named_parameters_free
parameters
parameter -
e_named_parameters_get
return -
e_xmlhash_new
return -
eds_check_version
return
I also found that each get-*
function has a null return on a type check error (such as g_return_val_if_fail (E_IS_SOURCE (source), NULL);
. I'm not sure if this counts as a nullable return value, since I'm not super familiar with gobject conventions.
I would like to submit a merge request for this, but I don't know enough about GIR to know what annotation to give each of these, since there are multiple versions of nullable annotations.