diff options
| author | Corentin Noël <corentin.noel@collabora.com> | 2023-03-01 01:21:38 +0100 |
|---|---|---|
| committer | Thomas Haller <thaller@redhat.com> | 2023-03-27 11:49:43 +0200 |
| commit | 5d28a0dd899bbe24f805758283173927c530291c (patch) | |
| tree | 0f0e7b62a729a691ed503c8781eb198efdb66f96 | |
| parent | 83d2ec2ec1364cf17029253709ac37c7528573a2 (diff) | |
| download | NetworkManager-5d28a0dd899bbe24f805758283173927c530291c.tar.gz | |
doc: replace all (allow-none) annotations by (optional) and/or (nullable)
The (allow-none) annotation is deprecated since a long time now, it is better to
use (nullable) and/or (optional) which clarifies what it means with the (out)
annotation.
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1551
70 files changed, 302 insertions, 296 deletions
diff --git a/src/core/devices/nm-device.c b/src/core/devices/nm-device.c index 6723d1415a..acea865566 100644 --- a/src/core/devices/nm-device.c +++ b/src/core/devices/nm-device.c @@ -6302,7 +6302,7 @@ attach_port_cb(NMDevice *self, GError *error, gpointer user_data) * nm_device_master_enslave_slave: * @self: the master device * @slave: the slave device to enslave - * @connection: (allow-none): the slave device's connection + * @connection: (nullable): the slave device's connection * * If @self is capable of enslaving other devices (ie it's a bridge, bond, team, * etc) then this function enslaves @slave. diff --git a/src/core/nm-act-request.c b/src/core/nm-act-request.c index 55d1829e7a..dce18ba4ec 100644 --- a/src/core/nm-act-request.c +++ b/src/core/nm-act-request.c @@ -416,8 +416,8 @@ nm_act_request_init(NMActRequest *req) /** * nm_act_request_new: * - * @settings_connection: (allow-none): the connection to activate @device with - * @applied_connection: (allow-none): the applied connection + * @settings_connection: (nullable): the connection to activate @device with + * @applied_connection: (nullable): the applied connection * @specific_object: the object path of the specific object (ie, Wi-Fi access point, * etc) that will be used to activate @connection and @device * @subject: the #NMAuthSubject representing the requestor of the activation diff --git a/src/core/nm-active-connection.c b/src/core/nm-active-connection.c index 6f62a601c2..36a11f7151 100644 --- a/src/core/nm-active-connection.c +++ b/src/core/nm-active-connection.c @@ -1153,7 +1153,7 @@ auth_done(NMAuthManager *auth_mgr, /** * nm_active_connection_authorize: * @self: the #NMActiveConnection - * @initial_connection: (allow-none): for add-and-activate, there + * @initial_connection: (nullable): for add-and-activate, there * is no @settings_connection available when creating the active connection. * Instead pass an alternative connection. * @result_func: function to be called on success or error diff --git a/src/core/nm-auth-utils.c b/src/core/nm-auth-utils.c index cef926fdf9..7739f44376 100644 --- a/src/core/nm-auth-utils.c +++ b/src/core/nm-auth-utils.c @@ -251,7 +251,7 @@ nm_auth_chain_steal_data(NMAuthChain *self, const char *tag) * @tag: the tag for referencing the attached data. * @data: the data to attach. If %NULL, this call has no effect * and nothing is attached. - * @data_destroy: (allow-none): the destroy function for the data pointer. + * @data_destroy: (nullable): the destroy function for the data pointer. * * @tag string is not cloned and must outlive @self. That is why * the function is "unsafe". Use nm_auth_chain_set_data() with a C literal diff --git a/src/core/nm-config.c b/src/core/nm-config.c index b74453628a..bcbc41cb49 100644 --- a/src/core/nm-config.c +++ b/src/core/nm-config.c @@ -1531,7 +1531,7 @@ nm_config_keyfile_has_global_dns_config(GKeyFile *keyfile, gboolean internal) * intern_config_read: * @filename: the filename where to store the internal config * @keyfile_conf: the merged configuration from user (/etc/NM/NetworkManager.conf). - * @out_needs_rewrite: (allow-none): whether the read keyfile contains inconsistent + * @out_needs_rewrite: (out) (optional): whether the read keyfile contains inconsistent * data (compared to @keyfile_conf). If %TRUE, you might want to rewrite * the file. * @@ -2058,7 +2058,7 @@ nm_config_set_connectivity_check_enabled(NMConfig *self, gboolean enabled) /** * nm_config_set_values: * @self: the NMConfig instance - * @keyfile_intern_new: (allow-none): the new internal settings to set. + * @keyfile_intern_new: (nullable): the new internal settings to set. * If %NULL, it is equal to an empty keyfile. * @allow_write: only if %TRUE, allow writing the changes to file. Otherwise, * do the changes in-memory only. diff --git a/src/core/nm-core-utils.c b/src/core/nm-core-utils.c index 15b3c6a80a..2686deef96 100644 --- a/src/core/nm-core-utils.c +++ b/src/core/nm-core-utils.c @@ -468,7 +468,7 @@ _kc_invoke_callback(pid_t pid, * @log_name: for logging, the name of the processes to kill * @wait_before_kill_msec: Waittime in milliseconds before sending %SIGKILL signal. Set this value * to zero, not to send %SIGKILL. If @sig is already %SIGKILL, this parameter is ignored. - * @callback: (allow-none): callback after the child terminated. This function will always + * @callback: (nullable): callback after the child terminated. This function will always * be invoked asynchronously. * @user_data: passed on to callback * @@ -601,7 +601,7 @@ _sleep_duration_convert_ms_to_us(guint32 sleep_duration_msec) * @log_domain: log debug information for this domain. Errors and warnings are logged both * as %LOGD_CORE and @log_domain. * @log_name: name of the process to kill for logging. - * @child_status: (out) (allow-none): return the exit status of the child, if no error occurred. + * @child_status: (out) (optional): return the exit status of the child, if no error occurred. * @wait_before_kill_msec: Waittime in milliseconds before sending %SIGKILL signal. Set this value * to zero, not to send %SIGKILL. If @sig is already %SIGKILL, this parameter has not effect. * @sleep_duration_msec: the synchronous function sleeps repeatedly waiting for the child to terminate. diff --git a/src/core/nm-keep-alive.c b/src/core/nm-keep-alive.c index e147163c1e..3ab5c36eb4 100644 --- a/src/core/nm-keep-alive.c +++ b/src/core/nm-keep-alive.c @@ -364,7 +364,7 @@ nm_keep_alive_disarm(NMKeepAlive *self) /** * nm_keep_alive_destroy: - * @self: (allow-none): the #NMKeepAlive instance to destroy. + * @self: (nullable): the #NMKeepAlive instance to destroy. * * This does 3 things in one: * diff --git a/src/core/nm-manager.c b/src/core/nm-manager.c index d04aa18b25..52f6304785 100644 --- a/src/core/nm-manager.c +++ b/src/core/nm-manager.c @@ -3268,7 +3268,7 @@ new_activation_allowed_for_connection(NMManager *self, NMSettingsConnection *con * get_existing_connection: * @manager: #NMManager instance * @device: #NMDevice instance - * @out_generated: (allow-none): return TRUE, if the connection was generated. + * @out_generated: (out) (optional): return TRUE, if the connection was generated. * * Returns: a #NMSettingsConnection to be assumed by the device, or %NULL if * the device does not support assuming existing connections. @@ -5982,7 +5982,7 @@ fail: * nm_manager_activate_connection(): * @self: the #NMManager * @sett_conn: the #NMSettingsConnection to activate on @device - * @applied: (allow-none): the applied connection to activate on @device + * @applied: (nullable): the applied connection to activate on @device * @specific_object: the specific object path, if any, for the activation * @device: the #NMDevice to activate @sett_conn on. Can be %NULL for VPNs. * @subject: the subject which requested activation diff --git a/src/core/settings/nm-secret-agent.c b/src/core/settings/nm-secret-agent.c index a3df449739..bb30034577 100644 --- a/src/core/settings/nm-secret-agent.c +++ b/src/core/settings/nm-secret-agent.c @@ -463,7 +463,7 @@ _call_cancel_cb(GObject *source, GAsyncResult *result, gpointer user_data) * nm_secret_agent_cancel_call: * @self: the #NMSecretAgent instance for the @call_id. * Maybe be %NULL if @call_id is %NULL. - * @call_id: (allow-none): the call id to cancel. May be %NULL for convenience, + * @call_id: (nullable): the call id to cancel. May be %NULL for convenience, * in which case it does nothing. * * It is an error to pass an invalid @call_id or a @call_id for an operation diff --git a/src/core/settings/nm-settings-connection.c b/src/core/settings/nm-settings-connection.c index b8cf0b5833..8d9ee08a99 100644 --- a/src/core/settings/nm-settings-connection.c +++ b/src/core/settings/nm-settings-connection.c @@ -1058,7 +1058,7 @@ get_secrets_idle_cb(NMSettingsConnectionCallId *call_id) /** * nm_settings_connection_get_secrets: * @self: the #NMSettingsConnection - * @applied_connection: (allow-none): if provided, only request secrets + * @applied_connection: (nullable): if provided, only request secrets * if @self equals to @applied_connection. Also, update the secrets * in the @applied_connection. * @subject: the #NMAuthSubject originating the request diff --git a/src/core/settings/nm-settings.c b/src/core/settings/nm-settings.c index d5edb7cd8b..c3d99cca3d 100644 --- a/src/core/settings/nm-settings.c +++ b/src/core/settings/nm-settings.c @@ -222,7 +222,7 @@ _sett_conn_entry_get_conn(SettConnEntry *sett_conn_entry) * _sett_conn_entry_storage_find_conflicting_storage: * @sett_conn_entry: the list of settings-storages for the given UUID. * @target_plugin: the settings plugin to check - * @storage_check_including: (allow-none): optionally compare against this storage. + * @storage_check_including: (nullable): optionally compare against this storage. * @plugins: the list of plugins sorted in descending priority. This determines * the priority and whether a storage conflicts. * @@ -1740,7 +1740,8 @@ _set_nmmeta_tombstone(NMSettings *self, * @persist_mode: the persist-mode for this profile. * @add_reason: the add-reason flags. * @sett_flags: the settings flags to set. - * @out_sett_conn: (allow-none) (transfer none): the added settings connection on success. + * @out_sett_conn: (out) (optional) (nullable) (transfer none): the added + * settings connection on success. * @error: on return, a location to store any errors that may occur * * Creates a new #NMSettingsConnection for the given source @connection. @@ -3114,7 +3115,7 @@ error: /** * nm_settings_get_connections: * @self: the #NMSettings - * @out_len: (out) (allow-none): returns the number of returned + * @out_len: (out) (optional): returns the number of returned * connections. * * Returns: (transfer none): a list of NMSettingsConnections. The list is @@ -3217,10 +3218,10 @@ nm_settings_get_connections_sorted_by_autoconnect_priority(NMSettings *self, gui /** * nm_settings_get_connections_clone: * @self: the #NMSetting - * @out_len: (allow-none): optional output argument + * @out_len: (optional): optional output argument * @func: caller-supplied function for filtering connections * @func_data: caller-supplied data passed to @func - * @sort_compare_func: (allow-none): optional function pointer for + * @sort_compare_func: (nullable): optional function pointer for * sorting the returned list. * @sort_data: user data for @sort_compare_func. * diff --git a/src/core/settings/plugins/ifcfg-rh/nms-ifcfg-rh-reader.c b/src/core/settings/plugins/ifcfg-rh/nms-ifcfg-rh-reader.c index a784662fd3..cb5b4c63eb 100644 --- a/src/core/settings/plugins/ifcfg-rh/nms-ifcfg-rh-reader.c +++ b/src/core/settings/plugins/ifcfg-rh/nms-ifcfg-rh-reader.c @@ -917,7 +917,7 @@ enum { * @options_route: (in-out): when line is from the OPTIONS setting, this is a pre-created * route object that is completed with the settings from options. Otherwise, * it shall point to %NULL and a new route is created and returned. - * @out_route: (out) (transfer full) (allow-none): the parsed %NMIPRoute instance. + * @out_route: (out) (transfer full) (optional): the parsed %NMIPRoute instance. * In case a @options_route is passed in, it returns the input route that was modified * in-place. But the caller must unref the returned route in either case. * @error: the failure description. diff --git a/src/core/settings/plugins/keyfile/nms-keyfile-plugin.c b/src/core/settings/plugins/keyfile/nms-keyfile-plugin.c index 1d7de8d24b..65b0243f13 100644 --- a/src/core/settings/plugins/keyfile/nms-keyfile-plugin.c +++ b/src/core/settings/plugins/keyfile/nms-keyfile-plugin.c @@ -1066,12 +1066,12 @@ delete_connection(NMSettingsPlugin *plugin, NMSettingsStorage *storage_x, GError * @shadowed_storage: a tombstone can also shadow an existing storage. * In combination with @set and @in_memory, this is allowed to store * the shadowed storage filename. - * @out_storage: (transfer full) (allow-none): the storage element that changes, or - * NULL if nothing changed. Note that the file on disk is already as - * we want to write it, then this still counts as a change. No change only + * @out_storage: (transfer full) (optional) (nullable): the storage element that + * changes, or %NULL if nothing changed. Note that the file on disk is already + * as we want to write it, then this still counts as a change. No change only * means if we try to delete a storage (@set %FALSE) that did not * exist previously. - * @out_hard_failure: (allow-none): on failure, indicate that this is a hard failure. + * @out_hard_failure: (optional): on failure, indicate that this is a hard failure. * * The function writes or deletes nmmeta files to/from filesystem. In this case, * the nmmeta files can only be symlinks to /dev/null (to indicate tombstones). diff --git a/src/libnm-client-impl/nm-client.c b/src/libnm-client-impl/nm-client.c index 4f98ae5620..bdf556f12e 100644 --- a/src/libnm-client-impl/nm-client.c +++ b/src/libnm-client-impl/nm-client.c @@ -4171,7 +4171,7 @@ nm_client_networking_get_enabled(NMClient *client) * nm_client_networking_set_enabled: * @client: a #NMClient * @enabled: %TRUE to set networking enabled, %FALSE to set networking disabled - * @error: (allow-none): return location for a #GError, or %NULL + * @error: return location for a #GError, or %NULL * * Enables or disables networking. When networking is disabled, all controlled * interfaces are disconnected and deactivated. When networking is enabled, @@ -4465,10 +4465,10 @@ nm_client_connectivity_check_get_uri(NMClient *client) /** * nm_client_get_logging: * @client: a #NMClient - * @level: (allow-none): return location for logging level string - * @domains: (allow-none): return location for log domains string. The string is + * @level: (nullable) (out) (optional): return location for logging level string + * @domains: (nullable) (out) (optional): return location for log domains string. The string is * a list of domains separated by "," - * @error: (allow-none): return location for a #GError, or %NULL + * @error: return location for a #GError, or %NULL * * Gets NetworkManager current logging level and domains. * @@ -4509,10 +4509,10 @@ nm_client_get_logging(NMClient *client, char **level, char **domains, GError **e /** * nm_client_set_logging: * @client: a #NMClient - * @level: (allow-none): logging level to set (%NULL or an empty string for no change) - * @domains: (allow-none): logging domains to set. The string should be a list of log + * @level: (nullable): logging level to set (%NULL or an empty string for no change) + * @domains: (nullable): logging domains to set. The string should be a list of log * domains separated by ",". (%NULL or an empty string for no change) - * @error: (allow-none): return location for a #GError, or %NULL + * @error: return location for a #GError, or %NULL * * Sets NetworkManager logging level and/or domains. * @@ -4733,7 +4733,7 @@ nm_client_check_connectivity_finish(NMClient *client, GAsyncResult *result, GErr /** * nm_client_save_hostname: * @client: the %NMClient - * @hostname: (allow-none): the new persistent hostname to set, or %NULL to + * @hostname: (nullable): the new persistent hostname to set, or %NULL to * clear any existing persistent hostname * @cancellable: a #GCancellable, or %NULL * @error: return location for #GError @@ -4769,7 +4769,7 @@ nm_client_save_hostname(NMClient *client, /** * nm_client_save_hostname_async: * @client: the %NMClient - * @hostname: (allow-none): the new persistent hostname to set, or %NULL to + * @hostname: (nullable): the new persistent hostname to set, or %NULL to * clear any existing persistent hostname * @cancellable: a #GCancellable, or %NULL * @callback: (scope async): callback to be called when the operation completes @@ -5026,9 +5026,9 @@ activate_connection_cb(GObject *object, GAsyncResult *result, gpointer user_data /** * nm_client_activate_connection_async: * @client: a #NMClient - * @connection: (allow-none): an #NMConnection - * @device: (allow-none): the #NMDevice - * @specific_object: (allow-none): the object path of a connection-type-specific + * @connection: (nullable): an #NMConnection + * @device: (nullable): the #NMDevice + * @specific_object: (nullable): the object path of a connection-type-specific * object this activation should use. This parameter is currently ignored for * wired and mobile broadband connections, and the value of %NULL should be used * (ie, no specific object). For Wi-Fi or WiMAX connections, pass the object @@ -5262,11 +5262,11 @@ _add_and_activate_connection(NMClient *self, /** * nm_client_add_and_activate_connection_async: * @client: a #NMClient - * @partial: (allow-none): an #NMConnection to add; the connection may be + * @partial: (nullable): an #NMConnection to add; the connection may be * partially filled (or even %NULL) and will be completed by NetworkManager * using the given @device and @specific_object before being added - * @device: (allow-none): the #NMDevice - * @specific_object: (allow-none): the object path of a connection-type-specific + * @device: (nullable): the #NMDevice + * @specific_object: (nullable): the object path of a connection-type-specific * object this activation should use. This parameter is currently ignored for * wired and mobile broadband connections, and the value of %NULL should be used * (ie, no specific object). For Wi-Fi or WiMAX connections, pass the object @@ -5336,11 +5336,11 @@ nm_client_add_and_activate_connection_finish(NMClient *client, GAsyncResult *res /** * nm_client_add_and_activate_connection2: * @client: a #NMClient - * @partial: (allow-none): an #NMConnection to add; the connection may be + * @partial: (nullable): an #NMConnection to add; the connection may be * partially filled (or even %NULL) and will be completed by NetworkManager * using the given @device and @specific_object before being added - * @device: (allow-none): the #NMDevice - * @specific_object: (allow-none): the object path of a connection-type-specific + * @device: (nullable): the #NMDevice + * @specific_object: (nullable): the object path of a connection-type-specific * object this activation should use. This parameter is currently ignored for * wired and mobile broadband connections, and the value of %NULL should be used * (i.e., no specific object). For Wi-Fi or WiMAX connections, pass the object @@ -5402,7 +5402,7 @@ nm_client_add_and_activate_connection2(NMClient *client, * @client: an #NMClient * @result: the result passed to the #GAsyncReadyCallback * @error: location for a #GError, or %NULL - * @out_result: (allow-none) (transfer full) (out): the output result + * @out_result: (optional) (nullable) (transfer full) (out): the output result * of type "a{sv}" returned by D-Bus' AddAndActivate2 call. Currently, no * output is implemented yet. * @@ -5833,7 +5833,7 @@ nm_client_add_connection_finish(NMClient *client, GAsyncResult *result, GError * * @client: the %NMClient * @settings: the "a{sa{sv}}" #GVariant with the content of the setting. * @flags: the %NMSettingsAddConnection2Flags argument. - * @args: (allow-none): the "a{sv}" #GVariant with extra argument or %NULL + * @args: (nullable): the "a{sv}" #GVariant with extra argument or %NULL * for no extra arguments. * @ignore_out_result: this function wraps AddConnection2(), which has an * additional result "a{sv}" output parameter. By setting this to %TRUE, @@ -5875,11 +5875,11 @@ nm_client_add_connection2(NMClient *client, * nm_client_add_connection2_finish: * @client: the #NMClient * @result: the #GAsyncResult - * @out_result: (allow-none) (transfer full) (out): the output #GVariant - * from AddConnection2(). + * @out_result: (optional) (nullable) (transfer full) (out): the output + * #GVariant from AddConnection2(). * If you care about the output result, then the "ignore_out_result" * parameter of nm_client_add_connection2() must not be set to %TRUE. - * @error: (allow-none): the error argument. + * @error: the error argument. * * Returns: (transfer full): on success, a pointer to the added * #NMRemoteConnection. @@ -6283,7 +6283,7 @@ _notify_update_prop_dns_manager_configuration(NMClient *self, /** * nm_client_get_capabilities: * @client: the #NMClient instance - * @length: (out) (allow-none): the number of returned capabilities. + * @length: (out) (optional): the number of returned capabilities. * * Returns: (transfer none) (array length=length): the * list of capabilities reported by the server or %NULL @@ -9063,8 +9063,8 @@ _wait_shutdown_cancelled_cb(GCancellable *cancellable, gpointer user_data) * that the client's maincontext gets iterated so that it can complete. * By integrating the maincontext in the current thread default, you * may instead only iterate the latter. - * @cancellable: (allow-none): the #GCancellable to abort the shutdown. - * @callback: (nullable): a #GAsyncReadyCallback to call when the request + * @cancellable: the #GCancellable to abort the shutdown. + * @callback: a #GAsyncReadyCallback to call when the request * is satisfied or %NULL if you don't care about the result of the * method invocation. * @user_data: the data to pass to @callback diff --git a/src/libnm-client-impl/nm-device-wifi-p2p.c b/src/libnm-client-impl/nm-device-wifi-p2p.c index 2b3b82f81d..535482adf1 100644 --- a/src/libnm-client-impl/nm-device-wifi-p2p.c +++ b/src/libnm-client-impl/nm-device-wifi-p2p.c @@ -130,7 +130,7 @@ nm_device_wifi_p2p_get_peer_by_path(NMDeviceWifiP2P *device, const char *path) /** * nm_device_wifi_p2p_start_find: * @device: a #NMDeviceWifiP2P - * @options: (allow-none): optional options passed to StartFind. + * @options: (nullable): optional options passed to StartFind. * @cancellable: a #GCancellable, or %NULL * @callback: a #GAsyncReadyCallback, or %NULL * @user_data: user_data for @callback diff --git a/src/libnm-client-impl/nm-device.c b/src/libnm-client-impl/nm-device.c index d5ecee48c1..e3e6ca6e0d 100644 --- a/src/libnm-client-impl/nm-device.c +++ b/src/libnm-client-impl/nm-device.c @@ -2366,7 +2366,7 @@ nm_device_is_software(NMDevice *device) /** * nm_device_reapply: * @device: a #NMDevice - * @connection: (allow-none): the #NMConnection to replace the applied + * @connection: (nullable): the #NMConnection to replace the applied * settings with or %NULL to reuse existing * @version_id: zero or the expected version id of the applied connection. * If specified and the version id mismatches, the call fails without @@ -2420,7 +2420,7 @@ nm_device_reapply(NMDevice *device, /** * nm_device_reapply_async: * @device: a #NMDevice - * @connection: (allow-none): the #NMConnection to replace the applied + * @connection: (nullable): the #NMConnection to replace the applied * settings with or %NULL to reuse existing * @version_id: zero or the expected version id of the applied * connection. If specified and the version id mismatches, the call @@ -2500,7 +2500,7 @@ nm_device_reapply_finish(NMDevice *device, GAsyncResult *result, GError **error) * nm_device_get_applied_connection: * @device: a #NMDevice * @flags: the flags argument. See #NMDeviceReapplyFlags. - * @version_id: (out) (allow-none): returns the current version id of + * @version_id: (out) (optional): returns the current version id of * the applied connection * @cancellable: a #GCancellable, or %NULL * @error: location for a #GError, or %NULL @@ -2601,7 +2601,7 @@ nm_device_get_applied_connection_async(NMDevice *device, * nm_device_get_applied_connection_finish: * @device: a #NMDevice * @result: the result passed to the #GAsyncReadyCallback - * @version_id: (out) (allow-none): the current version id of the applied + * @version_id: (out) (optional): the current version id of the applied * connection. * @error: location for a #GError, or %NULL * @@ -3108,7 +3108,8 @@ nm_lldp_neighbor_get_attr_names(NMLldpNeighbor *neighbor) * nm_lldp_neighbor_get_attr_string_value: * @neighbor: the #NMLldpNeighbor * @name: the attribute name - * @out_value: (out) (allow-none) (transfer none): on return, the attribute value + * @out_value: (out) (optional) (nullable) (transfer none): on return, the + * attribute value * * Gets the string value of attribute with name @name on @neighbor * @@ -3135,7 +3136,7 @@ nm_lldp_neighbor_get_attr_string_value(NMLldpNeighbor *neighbor, * nm_lldp_neighbor_get_attr_uint_value: * @neighbor: the #NMLldpNeighbor * @name: the attribute name - * @out_value: (out) (allow-none): on return, the attribute value + * @out_value: (out) (optional): on return, the attribute value * * Gets the uint32 value of attribute with name @name on @neighbor * diff --git a/src/libnm-client-impl/nm-remote-connection.c b/src/libnm-client-impl/nm-remote-connection.c index fe7e0712dc..38ea114b09 100644 --- a/src/libnm-client-impl/nm-remote-connection.c +++ b/src/libnm-client-impl/nm-remote-connection.c @@ -69,9 +69,9 @@ G_DEFINE_TYPE_WITH_CODE(NMRemoteConnection, /** * nm_remote_connection_update2: * @connection: the #NMRemoteConnection - * @settings: (allow-none): optional connection to update the settings. + * @settings: (nullable): optional connection to update the settings. * @flags: update-flags - * @args: (allow-none): optional arguments. + * @args: (nullable): optional arguments. * @cancellable: a #GCancellable, or %NULL * @callback: callback to be called when the commit operation completes * @user_data: caller-specific data passed to @callback diff --git a/src/libnm-core-aux-intern/nm-libnm-core-utils.c b/src/libnm-core-aux-intern/nm-libnm-core-utils.c index e7530c83b6..3e317e5b11 100644 --- a/src/libnm-core-aux-intern/nm-libnm-core-utils.c +++ b/src/libnm-core-aux-intern/nm-libnm-core-utils.c @@ -650,7 +650,7 @@ nm_utils_dnsname_normalize(int addr_family, const char *dns, char **out_free) /** * nm_setting_ovs_other_config_check_key: - * @key: (allow-none): the key to check + * @key: (nullable): the key to check * @error: a #GError, %NULL to ignore. * * Checks whether @key is a valid key for OVS' other-config. @@ -704,7 +704,7 @@ nm_setting_ovs_other_config_check_key(const char *key, GError **error) /** * nm_setting_ovs_other_config_check_val: - * @val: (allow-none): the value to check + * @val: (nullable): the value to check * @error: a #GError, %NULL to ignore. * * Checks whether @val is a valid user data value. This means, diff --git a/src/libnm-core-impl/nm-connection.c b/src/libnm-core-impl/nm-connection.c index f0583e6746..f0bc20aab8 100644 --- a/src/libnm-core-impl/nm-connection.c +++ b/src/libnm-core-impl/nm-connection.c @@ -765,7 +765,7 @@ diff_one_connection(NMConnection *a, * @b: a second #NMConnection to compare with the first * @flags: compare flags, e.g. %NM_SETTING_COMPARE_FLAG_EXACT * @out_settings: (out) (element-type utf8 GLib.HashTable(utf8,uint32)) - * (optional) (allow-none): if the connections differ, on return a hash table + * (optional) (nullable): if the connections differ, on return a hash table * mapping setting names to second-level GHashTable (utf8 to guint32), which * contains the key names that differ mapped to one or more of * %NMSettingDiffResult as a bitfield @@ -2073,12 +2073,12 @@ _connection_normalize(NMConnection *connection, /** * nm_connection_normalize: * @connection: the #NMConnection to normalize - * @parameters: (allow-none) (element-type utf8 gpointer): a #GHashTable with + * @parameters: (nullable) (element-type utf8 gpointer): a #GHashTable with * normalization parameters to allow customization of the normalization by providing * specific arguments. Unknown arguments will be ignored and the default will be * used. The keys must be strings compared with g_str_equal() function. * The values are opaque and depend on the parameter name. - * @modified: (out) (allow-none): outputs whether any settings were modified. + * @modified: (out) (optional): outputs whether any settings were modified. * @error: location to store error, or %NULL. Contains the reason, * why the connection is invalid, if the function returns an error. * @@ -2429,7 +2429,7 @@ _need_secrets(NMConnection *connection, gboolean check_rerequest, GPtrArray **hi /** * nm_connection_need_secrets: * @connection: the #NMConnection - * @hints: (out) (element-type utf8) (allow-none) (transfer container): + * @hints: (out) (element-type utf8) (nullable) (transfer container): * the address of a pointer to a #GPtrArray, initialized to %NULL, which on * return points to an allocated #GPtrArray containing the property names of * secrets of the #NMSetting which may be required; the caller owns the array @@ -2442,8 +2442,8 @@ _need_secrets(NMConnection *connection, gboolean check_rerequest, GPtrArray **hi * circumstances, there is no way to conclusively determine exactly which * secrets are needed. * - * Returns: the setting name of the #NMSetting object which has invalid or - * missing secrets + * Returns: (nullable): the setting name of the #NMSetting object which has + * invalid or missing secrets **/ const char * nm_connection_need_secrets(NMConnection *connection, GPtrArray **hints) @@ -2458,7 +2458,7 @@ nm_connection_need_secrets(NMConnection *connection, GPtrArray **hints) * nm_connection_need_secrets_for_rerequest: * @connection: the #NMConnection * - * Returns TRUE if some secret needs to be re-requested + * Returns: %TRUE if some secret needs to be re-requested **/ gboolean nm_connection_need_secrets_for_rerequest(NMConnection *connection) @@ -2484,7 +2484,7 @@ nm_connection_clear_secrets(NMConnection *connection) /** * nm_connection_clear_secrets_with_flags: * @connection: the #NMConnection - * @func: (scope call) (allow-none): function to be called to determine whether a + * @func: (scope call) (nullable): function to be called to determine whether a * specific secret should be cleared or not. If %NULL, all secrets are cleared. * @user_data: caller-supplied data passed to @func * @@ -2796,15 +2796,14 @@ _nm_connection_get_settings_arr(NMConnection *connection) /** * nm_connection_get_settings: * @connection: the #NMConnection instance - * @out_length: (allow-none) (out): the length of the returned array + * @out_length: (out) (optional): the length of the returned array * * Retrieves the settings in @connection. * * The returned array is %NULL-terminated. * - * Returns: (array length=out_length) (transfer container): a - * %NULL-terminated array containing every setting of - * @connection. + * Returns: (array length=out_length) (transfer container) (nullable): a + * %NULL-terminated array containing every setting of @connection. * If the connection has no settings, %NULL is returned. * * Since: 1.10 diff --git a/src/libnm-core-impl/nm-keyfile.c b/src/libnm-core-impl/nm-keyfile.c index 9a6ffc6f24..82581d9fea 100644 --- a/src/libnm-core-impl/nm-keyfile.c +++ b/src/libnm-core-impl/nm-keyfile.c @@ -3911,9 +3911,9 @@ nm_keyfile_read_ensure_uuid(NMConnection *connection, const char *fallback_uuid_ * the relative path is made absolute using @base_dir. This must * be an absolute path. * @handler_flags: the #NMKeyfileHandlerFlags. - * @handler: (allow-none) (scope call): read handler + * @handler: (nullable) (scope call): read handler * @user_data: user data for read handler - * @error: (allow-none) (out): error + * @error: error * * Tries to create a NMConnection from a keyfile. The resulting keyfile is * not normalized and might not even verify. @@ -4256,7 +4256,7 @@ _write_setting_wireguard(NMSetting *setting, KeyfileWriterInfo *info) * nm_keyfile_write: * @connection: the #NMConnection to persist to keyfile. * @handler_flags: the #NMKeyfileHandlerFlags. - * @handler: (allow-none) (scope call): optional handler for events and + * @handler: (nullable) (scope call): optional handler for events and * to override the default behavior. * @user_data: argument for @handler. * @error: the #GError in case writing fails. @@ -4554,13 +4554,14 @@ nm_keyfile_handler_data_fail_with_error(NMKeyfileHandlerData *handler_data, GErr /** * nm_keyfile_handler_data_get_context: * @handler_data: the #NMKeyfileHandlerData for any event. - * @out_kf_group_name: (out) (allow-none) (transfer none): if the event is in the - * context of a keyfile group, the group name. - * @out_kf_key_name: (out) (allow-none) (transfer none): if the event is in the - * context of a keyfile value, the key name. - * @out_cur_setting: (out) (allow-none) (transfer none): if the event happens while - * handling a particular #NMSetting instance. - * @out_cur_property_name: (out) (allow-none) (transfer none): the property name if applicable. + * @out_kf_group_name: (out) (optional) (nullable) (transfer none): if the event + * is in the context of a keyfile group, the group name. + * @out_kf_key_name: (out) (optional) (nullable) (transfer none): if the event + * is in the context of a keyfile value, the key name. + * @out_cur_setting: (out) (optional) (nullable) (transfer none): if the event + * happens while handling a particular #NMSetting instance. + * @out_cur_property_name: (out) (optional) (nullable) (transfer none): the + * property name if applicable. * * Get context information of the current event. This function can be called * on all events, but the context information may be unset. @@ -4605,8 +4606,8 @@ _nm_keyfile_handler_data_warn_get_message(const NMKeyfileHandlerData *handler_da * nm_keyfile_handler_data_warn_get: * @handler_data: the #NMKeyfileHandlerData for a %NM_KEYFILE_HANDLER_TYPE_WARN * event. - * @out_message: (out) (allow-none) (transfer none): the warning message. - * @out_severity: (out) (allow-none): the #NMKeyfileWarnSeverity warning severity. + * @out_message: (out) (optional) (transfer none): the warning message. + * @out_severity: (out) (optional): the #NMKeyfileWarnSeverity warning severity. * * Since: 1.30 */ diff --git a/src/libnm-core-impl/nm-setting-8021x.c b/src/libnm-core-impl/nm-setting-8021x.c index 1bc4de9d88..626673e87e 100644 --- a/src/libnm-core-impl/nm-setting-8021x.c +++ b/src/libnm-core-impl/nm-setting-8021x.c @@ -208,9 +208,9 @@ G_DEFINE_TYPE(NMSetting8021x, nm_setting_802_1x, NM_TYPE_SETTING) /** * nm_setting_802_1x_check_cert_scheme: - * @pdata: (allow-none): the data pointer + * @pdata: (nullable): the data pointer * @length: the length of the data - * @error: (allow-none) (out): validation reason + * @error: validation reason * * Determines and verifies the blob type. * When setting certificate properties of NMSetting8021x diff --git a/src/libnm-core-impl/nm-setting-bond.c b/src/libnm-core-impl/nm-setting-bond.c index a09129afb0..06a53e4a22 100644 --- a/src/libnm-core-impl/nm-setting-bond.c +++ b/src/libnm-core-impl/nm-setting-bond.c @@ -618,7 +618,7 @@ handle_error: /** * nm_setting_bond_validate_option: * @name: the name of the option to validate - * @value: (allow-none): the value of the option to validate. + * @value: (nullable): the value of the option to validate. * * Checks whether @name is a valid bond option and @value is a valid value for * the @name. If @value is %NULL, the function only validates the option name. @@ -720,13 +720,13 @@ nm_setting_bond_remove_option(NMSettingBond *setting, const char *name) /** * nm_setting_bond_get_valid_options: - * @setting: (allow-none): the #NMSettingBond + * @setting: (nullable): the #NMSettingBond * * Returns a list of valid bond options. * * The @setting argument is unused and may be passed as %NULL. * - * Returns: (transfer none): a %NULL-terminated array of strings of valid bond options. + * Returns: (transfer none) (nullable): a %NULL-terminated array of strings of valid bond options. **/ const char ** nm_setting_bond_get_valid_options(NMSettingBond *setting) diff --git a/src/libnm-core-impl/nm-setting-connection.c b/src/libnm-core-impl/nm-setting-connection.c index fe373c2c09..3cbcd9cdb2 100644 --- a/src/libnm-core-impl/nm-setting-connection.c +++ b/src/libnm-core-impl/nm-setting-connection.c @@ -398,7 +398,7 @@ nm_setting_connection_permissions_user_allowed(NMSettingConnection *setting, con * @setting: the #NMSettingConnection * @ptype: the permission type; at this time only "user" is supported * @pitem: the permission item formatted as required for @ptype - * @detail: (allow-none): unused at this time; must be %NULL + * @detail: (nullable): unused at this time; must be %NULL * * Adds a permission to the connection's permission list. At this time, only * the "user" permission type is supported, and @pitem must be a username. See @@ -481,7 +481,7 @@ nm_setting_connection_remove_permission(NMSettingConnection *setting, guint32 id * @setting: the #NMSettingConnection * @ptype: the permission type; at this time only "user" is supported * @pitem: the permission item formatted as required for @ptype - * @detail: (allow-none): unused at this time; must be %NULL + * @detail: (nullable): unused at this time; must be %NULL * * Removes the permission from the connection. * At this time, only the "user" permission type is supported, and @pitem must diff --git a/src/libnm-core-impl/nm-setting-ethtool.c b/src/libnm-core-impl/nm-setting-ethtool.c index d5199823e7..ab1ed0e2b6 100644 --- a/src/libnm-core-impl/nm-setting-ethtool.c +++ b/src/libnm-core-impl/nm-setting-ethtool.c @@ -25,7 +25,7 @@ /** * nm_ethtool_optname_is_feature: - * @optname: (allow-none): the option name to check + * @optname: (nullable): the option name to check * * Checks whether @optname is a valid option name for an offload feature. * @@ -45,7 +45,7 @@ nm_ethtool_optname_is_feature(const char *optname) /** * nm_ethtool_optname_is_coalesce: - * @optname: (allow-none): the option name to check + * @optname: (nullable): the option name to check * * Checks whether @optname is a valid option name for a coalesce setting. * @@ -61,7 +61,7 @@ nm_ethtool_optname_is_coalesce(const char *optname) /** * nm_ethtool_optname_is_ring: - * @optname: (allow-none): the option name to check + * @optname: (nullable): the option name to check * * Checks whether @optname is a valid option name for a ring setting. * @@ -77,7 +77,7 @@ nm_ethtool_optname_is_ring(const char *optname) /** * nm_ethtool_optname_is_pause: - * @optname: (allow-none): the option name to check + * @optname: (nullable): the option name to check * * Checks whether @optname is a valid option name for a pause setting. * diff --git a/src/libnm-core-impl/nm-setting-ip-config.c b/src/libnm-core-impl/nm-setting-ip-config.c index 40b121b6c3..ce4662b6c0 100644 --- a/src/libnm-core-impl/nm-setting-ip-config.c +++ b/src/libnm-core-impl/nm-setting-ip-config.c @@ -552,7 +552,7 @@ nm_ip_address_get_attribute(NMIPAddress *address, const char *name) * nm_ip_address_set_attribute: * @address: the #NMIPAddress * @name: the name of an address attribute - * @value: (transfer none) (allow-none): the value + * @value: (transfer none) (nullable): the value * * Sets or clears the named attribute on @address to the given value. **/ @@ -601,7 +601,7 @@ struct NMIPRoute { * <literal>AF_INET6</literal>) * @dest: the IP address of the route's destination * @prefix: the address prefix length - * @next_hop: (allow-none): the IP address of the next hop (or %NULL) + * @next_hop: (nullable): the IP address of the next hop (or %NULL) * @metric: the route metric (or -1 for "default") * @error: location to store error, or %NULL * @@ -652,7 +652,7 @@ nm_ip_route_new(int family, * <literal>AF_INET6</literal>) * @dest: the IP address of the route's destination * @prefix: the address prefix length - * @next_hop: (allow-none): the IP address of the next hop (or %NULL) + * @next_hop: (nullable): the IP address of the next hop (or %NULL) * @metric: the route metric (or -1 for "default") * @error: location to store error, or %NULL * @@ -994,7 +994,7 @@ nm_ip_route_get_next_hop(NMIPRoute *route) /** * nm_ip_route_set_next_hop: * @route: the #NMIPRoute - * @next_hop: (allow-none): the route's next hop, as a string + * @next_hop: (nullable): the route's next hop, as a string * * Sets the next-hop property of this route object. * @@ -1112,13 +1112,13 @@ _nm_ip_route_get_attributes(NMIPRoute *route) * @route: the #NMIPRoute * @sorted: whether to sort the names. Otherwise, their order is * undefined and unstable. - * @out_length: (allow-none) (out): the number of elements + * @out_length: (out) (optional): the number of elements * * Gets an array of attribute names defined on @route. * - * Returns: (array length=out_length) (transfer container): a %NULL-terminated array - * of attribute names or %NULL if there are no attributes. The order of the returned - * names depends on @sorted. + * Returns: (array length=out_length) (transfer container) (nullable): a %NULL-terminated + * array of attribute names or %NULL if there are no attributes. The order of the + * returned names depends on @sorted. **/ const char ** _nm_ip_route_get_attribute_names(const NMIPRoute *route, gboolean sorted, guint *out_length) @@ -1173,7 +1173,7 @@ nm_ip_route_get_attribute(NMIPRoute *route, const char *name) * nm_ip_route_set_attribute: * @route: the #NMIPRoute * @name: the name of a route attribute - * @value: (transfer none) (allow-none): the value + * @value: (transfer none) (nullable): the value * * Sets the named attribute on @route to the given value. **/ @@ -1460,7 +1460,7 @@ _ip_route_attribute_validate(const char *name, * @value: the attribute value * @family: IP address family of the route * @known: (out): on return, whether the attribute name is a known one - * @error: (allow-none): return location for a #GError, or %NULL + * @error: return location for a #GError, or %NULL * * Validates a route attribute, i.e. checks that the attribute is a known one * and the value is of the correct type and well-formed. @@ -1733,7 +1733,7 @@ nm_ip_routing_rule_new_clone(const NMIPRoutingRule *rule) /** * nm_ip_routing_rule_ref: - * @self: (allow-none): the #NMIPRoutingRule instance + * @self: (nullable): the #NMIPRoutingRule instance * * Increases the reference count of the instance. * @@ -1760,7 +1760,7 @@ nm_ip_routing_rule_ref(NMIPRoutingRule *self) /** * nm_ip_routing_rule_unref: - * @self: (allow-none): the #NMIPRoutingRule instance + * @self: (nullable): the #NMIPRoutingRule instance * * Decreases the reference count of the instance and destroys * the instance if the reference count reaches zero. @@ -1983,7 +1983,7 @@ nm_ip_routing_rule_set_from_bin(NMIPRoutingRule *self, gconstpointer from, guint /** * nm_ip_routing_rule_set_from: * @self: the #NMIPRoutingRule instance - * @from: (allow-none): the from/src address to set. + * @from: (nullable): the from/src address to set. * The address family must match. * @len: the corresponding prefix length of the address. * @@ -2083,7 +2083,7 @@ nm_ip_routing_rule_set_to_bin(NMIPRoutingRule *self, gconstpointer to, guint8 le /** * nm_ip_routing_rule_set_to: * @self: the #NMIPRoutingRule instance - * @to: (allow-none): the to/dst address to set. + * @to: (nullable): the to/dst address to set. * The address family must match. * @len: the corresponding prefix length of the address. * If @to is %NULL, this valid is ignored. @@ -2370,7 +2370,7 @@ nm_ip_routing_rule_get_xifname_bin(const NMIPRoutingRule *self, /** * nm_ip_routing_rule_set_iifname: * @self: the #NMIPRoutingRule instance. - * @iifname: (allow-none): the iifname to set or %NULL to unset. + * @iifname: (nullable): the iifname to set or %NULL to unset. * * The name supports C backslash escaping for non-UTF-8 characters. * Note that nm_ip_routing_rule_from_string() too uses backslash @@ -2407,7 +2407,7 @@ nm_ip_routing_rule_get_oifname(const NMIPRoutingRule *self) /** * nm_ip_routing_rule_set_oifname: * @self: the #NMIPRoutingRule instance. - * @oifname: (allow-none): the oifname to set or %NULL to unset. + * @oifname: (nullable): the oifname to set or %NULL to unset. * * The name supports C backslash escaping for non-UTF-8 characters. * Note that nm_ip_routing_rule_from_string() too uses backslash @@ -2525,9 +2525,9 @@ nm_ip_routing_rule_set_suppress_prefixlength(NMIPRoutingRule *self, gint32 suppr /** * nm_ip_routing_rule_get_uid_range: * @self: the #NMIPRoutingRule instance - * @out_range_start: (out) (allow-none): returns the start of the range + * @out_range_start: (out) (optional): returns the start of the range * or 0 if the range is not set. - * @out_range_end: (out) (allow-none): returns the end of the range + * @out_range_end: (out) (optional): returns the end of the range * or 0 if the range is not set. * * Returns: %TRUE if a uid range is set. @@ -2585,8 +2585,8 @@ nm_ip_routing_rule_set_uid_range(NMIPRoutingRule *self, /** * nm_ip_routing_rule_cmp: - * @rule: (allow-none): the #NMIPRoutingRule instance to compare - * @other: (allow-none): the other #NMIPRoutingRule instance to compare + * @rule: (nullable): the #NMIPRoutingRule instance to compare + * @other: (nullable): the other #NMIPRoutingRule instance to compare * * Returns: zero, a positive, or a negative integer to indicate * equality or how the arguments compare. @@ -2708,7 +2708,7 @@ _rr_xport_range_parse(char *str, gint64 *out_start, guint16 *out_end) /** * nm_ip_routing_rule_validate: * @self: the #NMIPRoutingRule instance to validate - * @error: (allow-none) (out): the error result if validation fails. + * @error: the error result if validation fails. * * Returns: %TRUE if the rule validates. * @@ -3348,9 +3348,9 @@ _rr_string_addr_family_from_flags(NMIPRoutingRuleAsStringFlags to_string_flags) * @str: the string representation to convert to an #NMIPRoutingRule * @to_string_flags: #NMIPRoutingRuleAsStringFlags for controlling the * string conversion. - * @extra_args: (allow-none): extra arguments for controlling the string + * @extra_args: (nullable): extra arguments for controlling the string * conversion. Currently, not extra arguments are supported. - * @error: (allow-none) (out): the error reason. + * @error: the error reason. * * Returns: (transfer full): the new #NMIPRoutingRule or %NULL on error. * @@ -3812,9 +3812,9 @@ _rr_string_append_inet_addr(NMStrBuf *str, * @self: the #NMIPRoutingRule instance to convert to string. * @to_string_flags: #NMIPRoutingRuleAsStringFlags for controlling the * string conversion. - * @extra_args: (allow-none): extra arguments for controlling the string + * @extra_args: (nullable): extra arguments for controlling the string * conversion. Currently, not extra arguments are supported. - * @error: (allow-none) (out): the error reason. + * @error: the error reason. * * Returns: (transfer full): the string representation or %NULL on error. * @@ -5348,7 +5348,7 @@ nm_setting_ip_config_get_dhcp_iaid(NMSettingIPConfig *setting) /** * nm_setting_ip_config_get_dhcp_reject_servers: * @setting: the #NMSettingIPConfig - * @out_len: (allow-none) (out): the number of returned elements + * @out_len: (out) (optional): the number of returned elements * * Returns: (array length=out_len zero-terminated=1) (transfer none): * A %NULL terminated array of DHCP reject servers. Even if no reject diff --git a/src/libnm-core-impl/nm-setting-match.c b/src/libnm-core-impl/nm-setting-match.c index f0e9fdf8d3..0ece65f15b 100644 --- a/src/libnm-core-impl/nm-setting-match.c +++ b/src/libnm-core-impl/nm-setting-match.c @@ -171,7 +171,7 @@ nm_setting_match_clear_interface_names(NMSettingMatch *setting) /** * nm_setting_match_get_interface_names: * @setting: the #NMSettingMatch - * @length: (out) (allow-none): the length of the returned interface names array. + * @length: (out) (optional): the length of the returned interface names array. * * Returns all the interface names. * @@ -317,7 +317,7 @@ nm_setting_match_clear_kernel_command_lines(NMSettingMatch *setting) /** * nm_setting_match_get_kernel_command_lines: * @setting: the #NMSettingMatch - * @length: (out) (allow-none): the length of the returned interface names array. + * @length: (out) (optional): the length of the returned interface names array. * * Returns all the interface names. * @@ -456,7 +456,7 @@ nm_setting_match_clear_drivers(NMSettingMatch *setting) /** * nm_setting_match_get_drivers: * @setting: the #NMSettingMatch - * @length: (out) (allow-none): the length of the returned interface names array. + * @length: (out) (optional): the length of the returned interface names array. * * Returns all the drivers. * @@ -595,7 +595,7 @@ nm_setting_match_clear_paths(NMSettingMatch *setting) /** * nm_setting_match_get_paths: * @setting: the #NMSettingMatch - * @length: (out) (allow-none): the length of the returned paths array. + * @length: (out) (optional): the length of the returned paths array. * * Returns all the paths. * diff --git a/src/libnm-core-impl/nm-setting-ovs-external-ids.c b/src/libnm-core-impl/nm-setting-ovs-external-ids.c index 5468438098..0cdf3e6bf6 100644 --- a/src/libnm-core-impl/nm-setting-ovs-external-ids.c +++ b/src/libnm-core-impl/nm-setting-ovs-external-ids.c @@ -56,7 +56,7 @@ G_DEFINE_TYPE(NMSettingOvsExternalIDs, nm_setting_ovs_external_ids, NM_TYPE_SETT /** * nm_setting_ovs_external_ids_check_key: - * @key: (allow-none): the key to check + * @key: (nullable): the key to check * @error: a #GError, %NULL to ignore. * * Checks whether @key is a valid key for OVS' external-ids. @@ -171,7 +171,7 @@ _nm_setting_ovs_verify_connection_type(GType gtype, NMConnection *connection, GE /** * nm_setting_ovs_external_ids_check_val: - * @val: (allow-none): the value to check + * @val: (nullable): the value to check * @error: a #GError, %NULL to ignore. * * Checks whether @val is a valid user data value. This means, @@ -297,7 +297,7 @@ nm_setting_ovs_external_ids_get_data(NMSettingOvsExternalIDs *setting, const cha * nm_setting_ovs_external_ids_set_data: * @setting: the #NMSettingOvsExternalIDs instance * @key: the key to set - * @val: (allow-none): the value to set or %NULL to clear a key. + * @val: (nullable): the value to set or %NULL to clear a key. * * Since: 1.30 */ diff --git a/src/libnm-core-impl/nm-setting-ovs-other-config.c b/src/libnm-core-impl/nm-setting-ovs-other-config.c index ca46ae9576..46d991d444 100644 --- a/src/libnm-core-impl/nm-setting-ovs-other-config.c +++ b/src/libnm-core-impl/nm-setting-ovs-other-config.c @@ -135,7 +135,7 @@ nm_setting_ovs_other_config_get_data(NMSettingOvsOtherConfig *setting, const cha * nm_setting_ovs_other_config_set_data: * @setting: the #NMSettingOvsOtherConfig instance * @key: the key to set - * @val: (allow-none): the value to set or %NULL to clear a key. + * @val: (nullable): the value to set or %NULL to clear a key. * * Since: 1.42 */ diff --git a/src/libnm-core-impl/nm-setting-sriov.c b/src/libnm-core-impl/nm-setting-sriov.c index 091cc0c645..b9faad564e 100644 --- a/src/libnm-core-impl/nm-setting-sriov.c +++ b/src/libnm-core-impl/nm-setting-sriov.c @@ -286,7 +286,7 @@ nm_sriov_vf_get_index(const NMSriovVF *vf) * nm_sriov_vf_set_attribute: * @vf: the #NMSriovVF * @name: the name of a route attribute - * @value: (transfer none) (allow-none): the value + * @value: (transfer none) (nullable): the value * * Sets the named attribute on @vf to the given value. * @@ -364,8 +364,8 @@ const NMVariantAttributeSpec *const _nm_sriov_vf_attribute_spec[] = { * nm_sriov_vf_attribute_validate: * @name: the attribute name * @value: the attribute value - * @known: (out): on return, whether the attribute name is a known one - * @error: (allow-none): return location for a #GError, or %NULL + * @known: (out) (optional): on return, whether the attribute name is a known one + * @error: return location for a #GError, or %NULL * * Validates a VF attribute, i.e. checks that the attribute is a known one, * the value is of the correct type and well-formed. @@ -533,7 +533,7 @@ vlan_id_compare(gconstpointer a, gconstpointer b, gpointer user_data) /** * nm_sriov_vf_get_vlan_ids: * @vf: the #NMSriovVF - * @length: (out) (allow-none): on return, the number of VLANs configured + * @length: (out) (optional): on return, the number of VLANs configured * * Returns the VLANs currently configured on the VF. Currently kernel only * supports one VLAN per VF. diff --git a/src/libnm-core-impl/nm-setting-tc-config.c b/src/libnm-core-impl/nm-setting-tc-config.c index 80135201c5..bb78890fbc 100644 --- a/src/libnm-core-impl/nm-setting-tc-config.c +++ b/src/libnm-core-impl/nm-setting-tc-config.c @@ -359,7 +359,7 @@ nm_tc_qdisc_get_attribute(NMTCQdisc *qdisc, const char *name) * nm_tc_qdisc_set_attribute: * @qdisc: the #NMTCQdisc * @name: the name of an qdisc attribute - * @value: (transfer none) (allow-none): the value + * @value: (transfer none) (nullable): the value * * Sets or clears the named attribute on @qdisc to the given value. * @@ -634,7 +634,7 @@ nm_tc_action_get_attribute(NMTCAction *action, const char *name) * nm_tc_action_set_attribute: * @action: the #NMTCAction * @name: the name of an action attribute - * @value: (transfer none) (allow-none): the value + * @value: (transfer none) (nullable): the value * * Sets or clears the named attribute on @action to the given value. * diff --git a/src/libnm-core-impl/nm-setting-team.c b/src/libnm-core-impl/nm-setting-team.c index e6e375e731..83de8b6fe0 100644 --- a/src/libnm-core-impl/nm-setting-team.c +++ b/src/libnm-core-impl/nm-setting-team.c @@ -143,7 +143,7 @@ nm_team_link_watcher_new_ethtool(int delay_up, int delay_down, GError **error) * @missed_max: missed_max value * @target_host: the host name or the ipv6 address that will be used as * target address in the NS packet - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Creates a new nsna_ping #NMTeamLinkWatcher object * @@ -223,7 +223,7 @@ nm_team_link_watcher_new_nsna_ping(int init_wait, * @source_host: the host name or the ip address that will be used as source * address in the arp request * @flags: the watcher #NMTeamLinkWatcherArpPingFlags - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Creates a new arp_ping #NMTeamLinkWatcher object * @@ -261,7 +261,7 @@ nm_team_link_watcher_new_arp_ping(int init_wait, * @source_host: the host name or the ip address that will be used as source * address in the arp request * @flags: the watcher #NMTeamLinkWatcherArpPingFlags - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Creates a new arp_ping #NMTeamLinkWatcher object * diff --git a/src/libnm-core-impl/nm-setting-user.c b/src/libnm-core-impl/nm-setting-user.c index 70bdc62a9e..8c2a9942fc 100644 --- a/src/libnm-core-impl/nm-setting-user.c +++ b/src/libnm-core-impl/nm-setting-user.c @@ -268,8 +268,8 @@ nm_setting_user_get_data(NMSettingUser *setting, const char *key) * nm_setting_user_set_data: * @setting: the #NMSettingUser instance * @key: the key to set - * @val: (allow-none): the value to set or %NULL to clear a key. - * @error: (allow-none): optional error argument + * @val: (nullable): the value to set or %NULL to clear a key. + * @error: optional error argument * * Since: 1.8 * diff --git a/src/libnm-core-impl/nm-setting-vlan.c b/src/libnm-core-impl/nm-setting-vlan.c index 696799d823..e5a99ce924 100644 --- a/src/libnm-core-impl/nm-setting-vlan.c +++ b/src/libnm-core-impl/nm-setting-vlan.c @@ -297,8 +297,8 @@ nm_setting_vlan_get_num_priorities(NMSettingVlan *setting, NMVlanPriorityMap map * @setting: the #NMSettingVlan * @map: the type of priority map * @idx: the zero-based index of the ingress/egress priority map entry - * @out_from: (out) (allow-none): on return the value of the priority map's 'from' item - * @out_to: (out) (allow-none): on return the value of priority map's 'to' item + * @out_from: (out) (optional): on return the value of the priority map's 'from' item + * @out_to: (out) (optional): on return the value of priority map's 'to' item * * Retrieve one of the entries of the #NMSettingVlan:ingress_priority_map * or #NMSettingVlan:egress_priority_map properties of this setting. diff --git a/src/libnm-core-impl/nm-setting-vpn.c b/src/libnm-core-impl/nm-setting-vpn.c index 4ff989087c..5984f773a0 100644 --- a/src/libnm-core-impl/nm-setting-vpn.c +++ b/src/libnm-core-impl/nm-setting-vpn.c @@ -178,7 +178,7 @@ nm_setting_vpn_get_num_data_items(NMSettingVpn *setting) * nm_setting_vpn_add_data_item: * @setting: the #NMSettingVpn * @key: a name that uniquely identifies the given value @item - * @item: (allow-none): the value to be referenced by @key + * @item: (nullable): the value to be referenced by @key * * Establishes a relationship between @key and @item internally in the * setting which may be retrieved later. Should not be used to store passwords @@ -227,11 +227,11 @@ nm_setting_vpn_get_data_item(NMSettingVpn *setting, const char *key) /** * nm_setting_vpn_get_data_keys: * @setting: the #NMSettingVpn - * @out_length: (allow-none) (out): the length of the returned array + * @out_length: (out) (optional): the length of the returned array * * Retrieves every data key inside @setting, as an array. * - * Returns: (array length=out_length) (transfer container): a + * Returns: (array length=out_length) (transfer container) (nullable): a * %NULL-terminated array containing each data key or %NULL if * there are no data items. * @@ -346,7 +346,7 @@ nm_setting_vpn_get_num_secrets(NMSettingVpn *setting) * nm_setting_vpn_add_secret: * @setting: the #NMSettingVpn * @key: a name that uniquely identifies the given secret @secret - * @secret: (allow-none): the secret to be referenced by @key + * @secret: (nullable): the secret to be referenced by @key * * Establishes a relationship between @key and @secret internally in the * setting which may be retrieved later. @@ -394,11 +394,11 @@ nm_setting_vpn_get_secret(NMSettingVpn *setting, const char *key) /** * nm_setting_vpn_get_secret_keys: * @setting: the #NMSettingVpn - * @out_length: (allow-none) (out): the length of the returned array + * @out_length: (out) (optional): the length of the returned array * * Retrieves every secret key inside @setting, as an array. * - * Returns: (array length=out_length) (transfer container): a + * Returns: (array length=out_length) (transfer container) (nullable): a * %NULL-terminated array containing each secret key or %NULL if * there are no secrets. * diff --git a/src/libnm-core-impl/nm-setting-wired.c b/src/libnm-core-impl/nm-setting-wired.c index 3acd5d97d5..f171048d6f 100644 --- a/src/libnm-core-impl/nm-setting-wired.c +++ b/src/libnm-core-impl/nm-setting-wired.c @@ -507,11 +507,12 @@ nm_setting_wired_get_num_s390_options(NMSettingWired *setting) * @setting: the #NMSettingWired * @idx: index of the desired option, from 0 to * nm_setting_wired_get_num_s390_options() - 1 - * @out_key: (allow-none) (out) (transfer none): on return, the key name of the s390 specific - * option; this value is owned by the setting and should not be modified - * @out_value: (allow-none) (out) (transfer none): on return, the value of the key of the - * s390 specific option; this value is owned by the setting and should not be - * modified + * @out_key: (optional) (nullable) (out) (transfer none): on return, the key + * name of the s390 specific option; this value is owned by the setting and + * should not be modified + * @out_value: (optional) (nullable) (out) (transfer none): on return, the value + * of the key of the s390 specific option; this value is owned by the setting + * and should not be modified * * Given an index, return the value of the s390 option at that index. indexes * are *not* guaranteed to be static across modifications to options done by @@ -701,7 +702,7 @@ _nm_setting_wired_clear_s390_options(NMSettingWired *setting) /** * nm_setting_wired_get_valid_s390_options: - * @setting: (allow-none): the #NMSettingWired. This argument is unused + * @setting: (nullable): the #NMSettingWired. This argument is unused * and you may pass %NULL. * * Returns a list of valid s390 options. diff --git a/src/libnm-core-impl/nm-setting-wireguard.c b/src/libnm-core-impl/nm-setting-wireguard.c index a981187f10..4a30985bc3 100644 --- a/src/libnm-core-impl/nm-setting-wireguard.c +++ b/src/libnm-core-impl/nm-setting-wireguard.c @@ -125,7 +125,7 @@ nm_wireguard_peer_new_clone(const NMWireGuardPeer *self, gboolean with_secrets) /** * nm_wireguard_peer_ref: - * @self: (allow-none): the #NMWireGuardPeer instance + * @self: (nullable): the #NMWireGuardPeer instance * * Returns: returns the input argument @self after incrementing * the reference count. @@ -150,7 +150,7 @@ nm_wireguard_peer_ref(NMWireGuardPeer *self) /** * nm_wireguard_peer_unref: - * @self: (allow-none): the #NMWireGuardPeer instance + * @self: (nullable): the #NMWireGuardPeer instance * * Drop a reference to @self. If the last reference is dropped, * the instance is freed and all associate data released. @@ -260,7 +260,7 @@ nm_wireguard_peer_get_public_key(const NMWireGuardPeer *self) /** * nm_wireguard_peer_set_public_key: * @self: the unsealed #NMWireGuardPeer instance - * @public_key: (allow-none) (transfer none): the new public + * @public_key: (nullable) (transfer none): the new public * key or %NULL to clear the public key. * @accept_invalid: if %TRUE and @public_key is not %NULL and * invalid, then do not modify the instance. @@ -339,7 +339,7 @@ nm_wireguard_peer_get_preshared_key(const NMWireGuardPeer *self) /** * nm_wireguard_peer_set_preshared_key: * @self: the unsealed #NMWireGuardPeer instance - * @preshared_key: (allow-none) (transfer none): the new preshared + * @preshared_key: (nullable) (transfer none): the new preshared * key or %NULL to clear the preshared key. * @accept_invalid: whether to allow setting the key to an invalid * value. If %FALSE, @self is unchanged if the key is invalid @@ -564,13 +564,13 @@ nm_wireguard_peer_get_allowed_ips_len(const NMWireGuardPeer *self) * @self: the #NMWireGuardPeer instance * @idx: the index from zero to (allowed-ips-len - 1) to * retrieve. - * @out_is_valid: (allow-none): %TRUE if the returned value is a valid allowed-ip + * @out_is_valid: (optional): %TRUE if the returned value is a valid allowed-ip * setting. * This parameter is wrongly not marked as (out) argument, it is * thus not accessible via introspection. This cannot be fixed without * breaking API for introspection users. * - * Returns: (transfer none): the allowed-ip setting at index @idx. + * Returns: (transfer none) (nullable): the allowed-ip setting at index @idx. * If @idx is out of range, %NULL will be returned. * * Since: 1.16 @@ -813,8 +813,8 @@ nm_wireguard_peer_is_valid(const NMWireGuardPeer *self, /** * nm_wireguard_peer_cmp: - * @a: (allow-none): the #NMWireGuardPeer to compare. - * @b: (allow-none): the other #NMWireGuardPeer to compare. + * @a: (nullable): the #NMWireGuardPeer to compare. + * @b: (nullable): the other #NMWireGuardPeer to compare. * @compare_flags: #NMSettingCompareFlags to affect the comparison. * * Returns: zero of the two instances are equivalent or @@ -1222,11 +1222,11 @@ nm_setting_wireguard_get_peer(NMSettingWireGuard *self, guint idx) * @self: the #NMSettingWireGuard instance * @public_key: the public key for looking up the * peer. - * @out_idx: (out) (allow-none): optional output argument + * @out_idx: (out) (optional): optional output argument * for the index of the found peer. If no index is found, * this is set to the nm_setting_wireguard_get_peers_len(). * - * Returns: (transfer none): the #NMWireGuardPeer instance with a + * Returns: (transfer none) (nullable): the #NMWireGuardPeer instance with a * matching public key. If no such peer exists, %NULL is returned. * * Since: 1.16 diff --git a/src/libnm-core-impl/nm-setting.c b/src/libnm-core-impl/nm-setting.c index 5a46a1b439..8e1edb0036 100644 --- a/src/libnm-core-impl/nm-setting.c +++ b/src/libnm-core-impl/nm-setting.c @@ -2383,7 +2383,7 @@ nm_setting_get_name(NMSetting *setting) /** * nm_setting_verify: * @setting: the #NMSetting to verify - * @connection: (allow-none): the #NMConnection that @setting came from, or + * @connection: (nullable): the #NMConnection that @setting came from, or * %NULL if @setting is being verified in isolation. * @error: location to store error, or %NULL * @@ -2421,7 +2421,7 @@ _nm_setting_verify(NMSetting *setting, NMConnection *connection, GError **error) /** * nm_setting_verify_secrets: * @setting: the #NMSetting to verify secrets in - * @connection: (allow-none): the #NMConnection that @setting came from, or + * @connection: (nullable): the #NMConnection that @setting came from, or * %NULL if @setting is being verified in isolation. * @error: location to store error, or %NULL * @@ -3828,11 +3828,11 @@ out_zero: /** * nm_setting_option_get_all_names: * @setting: the #NMSetting - * @out_len: (allow-none) (out): + * @out_len: (out) (optional): * * Gives the name of all set options. * - * Returns: (array length=out_len zero-terminated=1) (transfer none): + * Returns: (array length=out_len zero-terminated=1) (transfer none) (nullable): * A %NULL terminated array of key names. If no names are present, this returns * %NULL. The returned array and the names are owned by %NMSetting and might be invalidated * by the next operation. @@ -3870,7 +3870,7 @@ _nm_setting_option_clear(NMSetting *setting, const char *optname) /** * nm_setting_option_clear_by_name: * @setting: the #NMSetting - * @predicate: (allow-none) (scope call): the predicate for which names + * @predicate: (nullable) (scope call): the predicate for which names * should be clear. * If the predicate returns %TRUE for an option name, the option * gets removed. If %NULL, all options will be removed. @@ -3937,7 +3937,7 @@ nm_setting_option_get(NMSetting *setting, const char *opt_name) * nm_setting_option_get_boolean: * @setting: the #NMSetting * @opt_name: the option to get - * @out_value: (allow-none) (out): the optional output value. + * @out_value: (nullable) (out): the optional output value. * If the option is unset, %FALSE will be returned. * * Returns: %TRUE if @opt_name is set to a boolean variant. @@ -3962,7 +3962,7 @@ nm_setting_option_get_boolean(NMSetting *setting, const char *opt_name, gboolean * nm_setting_option_get_uint32: * @setting: the #NMSetting * @opt_name: the option to get - * @out_value: (allow-none) (out): the optional output value. + * @out_value: (nullable) (out): the optional output value. * If the option is unset, 0 will be returned. * * Returns: %TRUE if @opt_name is set to a uint32 variant. @@ -3987,7 +3987,7 @@ nm_setting_option_get_uint32(NMSetting *setting, const char *opt_name, guint32 * * nm_setting_option_set: * @setting: the #NMSetting * @opt_name: the option name to set - * @variant: (allow-none): the variant to set. + * @variant: (nullable): the variant to set. * * If @variant is %NULL, this clears the option if it is set. * Otherwise, @variant is set as the option. If @variant is @@ -4287,7 +4287,7 @@ nm_range_to_str(const NMRange *range) /** * nm_range_from_str: * @str: the string representation of a range - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Parses the string representation of the range to create a %NMRange * instance. diff --git a/src/libnm-core-impl/nm-utils.c b/src/libnm-core-impl/nm-utils.c index c389213f3f..9142f82be2 100644 --- a/src/libnm-core-impl/nm-utils.c +++ b/src/libnm-core-impl/nm-utils.c @@ -175,7 +175,7 @@ nm_sock_addr_endpoint_new(const char *endpoint) /** * nm_sock_addr_endpoint_ref: - * @self: (allow-none): the #NMSockAddrEndpoint + * @self: (nullable): the #NMSockAddrEndpoint */ NMSockAddrEndpoint * nm_sock_addr_endpoint_ref(NMSockAddrEndpoint *self) @@ -193,7 +193,7 @@ nm_sock_addr_endpoint_ref(NMSockAddrEndpoint *self) /** * nm_sock_addr_endpoint_unref: - * @self: (allow-none): the #NMSockAddrEndpoint + * @self: (nullable): the #NMSockAddrEndpoint */ void nm_sock_addr_endpoint_unref(NMSockAddrEndpoint *self) @@ -1380,7 +1380,7 @@ nm_utils_ip4_dns_from_variant(GVariant *value) /** * nm_utils_ip4_addresses_to_variant: * @addresses: (element-type NMIPAddress): an array of #NMIPAddress objects - * @gateway: (allow-none): the gateway IP address + * @gateway: (nullable): the gateway IP address * * Utility function to convert a #GPtrArray of #NMIPAddress objects representing * IPv4 addresses into a #GVariant of type 'aau' representing an array of @@ -1430,7 +1430,8 @@ nm_utils_ip4_addresses_to_variant(GPtrArray *addresses, const char *gateway) /** * nm_utils_ip4_addresses_from_variant: * @value: a #GVariant of type 'aau' - * @out_gateway: (out) (allow-none) (transfer full): on return, will contain the IP gateway + * @out_gateway: (out) (optional) (nullable) (transfer full): on return, will + * contain the IP gateway * * Utility function to convert a #GVariant of type 'aau' representing a list of * NetworkManager IPv4 addresses (which are tuples of address, prefix, and @@ -1673,7 +1674,7 @@ nm_utils_ip6_dns_from_variant(GVariant *value) /** * nm_utils_ip6_addresses_to_variant: * @addresses: (element-type NMIPAddress): an array of #NMIPAddress objects - * @gateway: (allow-none): the gateway IP address + * @gateway: (nullable): the gateway IP address * * Utility function to convert a #GPtrArray of #NMIPAddress objects representing * IPv6 addresses into a #GVariant of type 'a(ayuay)' representing an array of @@ -1725,7 +1726,8 @@ nm_utils_ip6_addresses_to_variant(GPtrArray *addresses, const char *gateway) /** * nm_utils_ip6_addresses_from_variant: * @value: a #GVariant of type 'a(ayuay)' - * @out_gateway: (out) (allow-none) (transfer full): on return, will contain the IP gateway + * @out_gateway: (out) (optional) (nullable) (transfer full): on return, will + * contain the IP gateway * * Utility function to convert a #GVariant of type 'a(ayuay)' representing a * list of NetworkManager IPv6 addresses (which are tuples of address, prefix, @@ -2821,7 +2823,7 @@ extern const NMVariantAttributeSpec *const _nm_sriov_vf_attribute_spec[]; * nm_utils_sriov_vf_to_str: * @vf: the %NMSriovVF * @omit_index: if %TRUE, the VF index will be omitted from output string - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Converts a SR-IOV virtual function object to its string representation. * @@ -2982,7 +2984,7 @@ _nm_sriov_vf_parse_vlans(NMSriovVF *vf, const char *str, GError **error) /** * nm_utils_sriov_vf_from_str: * @str: the input string - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Converts a string to a SR-IOV virtual function object. * @@ -3210,17 +3212,17 @@ _nm_utils_check_module_file(const char *name, * nm_utils_file_search_in_paths: * @progname: the helper program name, like "iptables" * Must be a non-empty string, without path separator (/). - * @try_first: (allow-none): a custom path to try first before searching. + * @try_first: (nullable): a custom path to try first before searching. * It is silently ignored if it is empty or not an absolute path. - * @paths: (allow-none): a %NULL terminated list of search paths. + * @paths: (nullable): a %NULL terminated list of search paths. * Can be empty or %NULL, in which case only @try_first is checked. * @file_test_flags: the flags passed to g_file_test() when searching * for @progname. Set it to 0 to skip the g_file_test(). * @predicate: (scope call): if given, pass the file name to this function * for additional checks. This check is performed after the check for * @file_test_flags. You cannot omit both @file_test_flags and @predicate. - * @user_data: (closure) (allow-none): user data for @predicate function. - * @error: (allow-none): on failure, set a "not found" error %G_IO_ERROR %G_IO_ERROR_NOT_FOUND. + * @user_data: (closure) (nullable): user data for @predicate function. + * @error: on failure, set a "not found" error %G_IO_ERROR %G_IO_ERROR_NOT_FOUND. * * Searches for a @progname file in a list of search @paths. * @@ -4296,7 +4298,7 @@ nm_utils_is_valid_iface_name_utf8safe(const char *utf8safe_name) /** * nm_utils_is_valid_iface_name: - * @name: (allow-none): Name of interface + * @name: (nullable): Name of interface * @error: location to store the error occurring, or %NULL to ignore * * Validate the network interface name. @@ -4321,7 +4323,7 @@ nm_utils_is_valid_iface_name(const char *name, GError **error) /** * nm_utils_iface_valid_name: - * @name: (allow-none): Name of interface + * @name: (nullable): Name of interface * * Validate the network interface name. * @@ -4340,7 +4342,7 @@ nm_utils_iface_valid_name(const char *name) /** * nm_utils_is_uuid: - * @str: (allow-none): a string that might be a UUID + * @str: (nullable): a string that might be a UUID * * Checks if @str is a UUID * @@ -4711,10 +4713,10 @@ validate_dns_option(const char *name, /** * _nm_utils_dns_option_validate: * @option: option string - * @out_name: (out) (allow-none): the option name - * @out_value: (out) (allow-none): the option value + * @out_name: (out) (optional) (nullable): the option name + * @out_value: (out) (optional): the option value * @ipv6: whether the option refers to a IPv6 configuration - * @option_descs: (allow-none): an array of NMUtilsDNSOptionDesc which describes the + * @option_descs: (nullable): an array of NMUtilsDNSOptionDesc which describes the * valid options * * Parses a DNS option in the form "name" or "name:number" and, if @@ -4834,8 +4836,9 @@ nm_utils_enum_to_str(GType type, int value) * nm_utils_enum_from_str: * @type: the %GType of the enum * @str: the input string - * @out_value: (out) (allow-none): the output value - * @err_token: (out) (allow-none) (transfer full): location to store the first unrecognized token + * @out_value: (out) (optional): the output value + * @err_token: (out) (optional) (nullable) (transfer full): location to store + * the first unrecognized token * * Converts a string to the matching enum value. * @@ -5030,7 +5033,7 @@ _nm_variant_attribute_spec_find_binary_search(const NMVariantAttributeSpec *cons * @key_value_separator: character separating key and values * @ignore_unknown: whether unknown attributes should be ignored * @spec: the attribute format specifiers - * @error: (out) (allow-none): location to store the error on failure + * @error: location to store the error on failure * * Parse attributes from a string. * @@ -5330,7 +5333,7 @@ NM_UTILS_FLAGS2STR_DEFINE(nm_bluetooth_capability_to_string, * @base64_key: the (possibly invalid) base64 encode key. * @required_key_len: the expected (binary) length of the key after * decoding. If the length does not match, the validation fails. - * @out_key: (allow-none): (out): an optional output buffer for the binary + * @out_key: (optional): (out): an optional output buffer for the binary * key. If given, it will be filled with exactly @required_key_len * bytes. * diff --git a/src/libnm-core-impl/nm-vpn-editor-plugin.c b/src/libnm-core-impl/nm-vpn-editor-plugin.c index 3a6abbc2ad..6c9aff43c6 100644 --- a/src/libnm-core-impl/nm-vpn-editor-plugin.c +++ b/src/libnm-core-impl/nm-vpn-editor-plugin.c @@ -129,7 +129,7 @@ nm_vpn_editor_plugin_get_plugin_info(NMVpnEditorPlugin *plugin) /** * nm_vpn_editor_plugin_set_plugin_info: * @plugin: the #NMVpnEditorPlugin instance - * @plugin_info: (allow-none): a #NMVpnPluginInfo instance or %NULL + * @plugin_info: (nullable): a #NMVpnPluginInfo instance or %NULL * * Set or clear the plugin-info instance. * This takes a weak reference on @plugin_info, to avoid circular diff --git a/src/libnm-core-impl/nm-vpn-plugin-info.c b/src/libnm-core-impl/nm-vpn-plugin-info.c index 61e9cde510..d2ce9ed827 100644 --- a/src/libnm-core-impl/nm-vpn-plugin-info.c +++ b/src/libnm-core-impl/nm-vpn-plugin-info.c @@ -143,7 +143,7 @@ nm_vpn_plugin_info_check_file_full(const char *filename, * other users. * @check_file: pass a callback to do your own validation. * @user_data: user data for @check_file. - * @error: (allow-none) (out): the error reason if the check fails. + * @error: the error reason if the check fails. * * Check whether the file exists and is a valid name file (in keyfile format). * Additionally, also check for file permissions. @@ -236,7 +236,7 @@ _nm_vpn_plugin_info_get_default_dir_user(void) * @check_owner: if set to a non-negative number, check that the file * owner is either the same uid or 0. In that case, also check * that the file is not writable by group or other. - * @check_file: (allow-none): callback to check whether the file is valid. + * @check_file: (nullable): callback to check whether the file is valid. * @user_data: data for @check_file * * Iterate over the content of @dirname and load name files. @@ -352,16 +352,16 @@ nm_vpn_plugin_info_list_load(void) /** * nm_vpn_plugin_info_new_search_file: - * @name: (allow-none): the name to search for. Either @name or @service + * @name: (nullable): the name to search for. Either @name or @service * must be present. - * @service: (allow-none): the service to search for. Either @name or + * @service: (nullable): the service to search for. Either @name or * @service must be present. * * This has the same effect as doing a full nm_vpn_plugin_info_list_load() * followed by a search for the first matching VPN plugin info that has the * given @name and/or @service. * - * Returns: (transfer full): a newly created instance of plugin info + * Returns: (transfer full) (nullable): a newly created instance of plugin info * or %NULL if no matching value was found. * * Since: 1.4 @@ -987,7 +987,7 @@ nm_vpn_plugin_info_get_editor_plugin(NMVpnPluginInfo *self) /** * nm_vpn_plugin_info_set_editor_plugin: * @self: plugin info instance - * @plugin: (allow-none): plugin instance + * @plugin: (nullable): plugin instance * * Set the internal plugin instance. If %NULL, only clear the previous instance. * diff --git a/src/libnm-crypto/nm-crypto.c b/src/libnm-crypto/nm-crypto.c index 8cf6633632..7fcff4a9f7 100644 --- a/src/libnm-crypto/nm-crypto.c +++ b/src/libnm-crypto/nm-crypto.c @@ -899,9 +899,9 @@ nm_crypto_randomize(void *buffer, gsize buffer_len, GError **error) * nmtst_crypto_rsa_key_encrypt: * @data: (array length=len): RSA private key data to be encrypted * @len: length of @data - * @in_password: (allow-none): existing password to use, if any - * @out_password: (out) (allow-none): if @in_password was %NULL, a random - * password will be generated and returned in this argument + * @in_password: (nullable): existing password to use, if any + * @out_password: (out) (optional) (nullable): if @in_password was %NULL, a + * random password will be generated and returned in this argument * @error: detailed error information on return, if an error occurred * * Encrypts the given RSA private key data with the given password (or generates diff --git a/src/libnm-glib-aux/nm-dbus-aux.c b/src/libnm-glib-aux/nm-dbus-aux.c index 3925da55bc..5c4dbc492c 100644 --- a/src/libnm-glib-aux/nm-dbus-aux.c +++ b/src/libnm-glib-aux/nm-dbus-aux.c @@ -454,8 +454,8 @@ _bus_get_cb(GObject *source, GAsyncResult *result, gpointer user_data) /** * nm_g_bus_get_blocking: - * @cancellable: (allow-none): a #GCancellable to abort the operation. - * @error: (allow-none): the error. + * @cancellable: a #GCancellable to abort the operation. + * @error: the error. * * This calls g_bus_get(), but iterates the current (thread-default) GMainContext * until the response is ready. As such, it's similar to g_bus_get_sync(), @@ -605,10 +605,10 @@ dbus_signal_meta_marshal(GClosure *closure, * _nm_dbus_proxy_signal_connect_data: * @proxy: a #GDBusProxy * @signal_name: the D-Bus signal to connect to - * @signature: (allow-none): the signal's type signature (must be a tuple) + * @signature: (nullable): the signal's type signature (must be a tuple) * @c_handler: the signal handler function - * @data: (allow-none): data to pass to @c_handler - * @destroy_data: (allow-none): closure destroy notify for @data + * @data: (nullable): data to pass to @c_handler + * @destroy_data: (nullable): closure destroy notify for @data * @connect_flags: connection flags * * Connects to the D-Bus signal @signal_name on @proxy. @c_handler must be a @@ -690,7 +690,7 @@ _nm_dbus_typecheck_response(GVariant *response, const GVariantType *reply_type, * @proxy: A #GDBusProxy. * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to * g_dbus_proxy_call(). - * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @reply_type: (nullable): the expected type of the reply, or %NULL * @error: Return location for error or %NULL. * * Finishes an operation started with g_dbus_proxy_call(), as with diff --git a/src/libnm-glib-aux/nm-dbus-aux.h b/src/libnm-glib-aux/nm-dbus-aux.h index 5db79c08f7..5bbb01e99f 100644 --- a/src/libnm-glib-aux/nm-dbus-aux.h +++ b/src/libnm-glib-aux/nm-dbus-aux.h @@ -290,7 +290,7 @@ gulong _nm_dbus_proxy_signal_connect_data(GDBusProxy *proxy, * @signal_name: the D-Bus signal to connect to * @signature: the signal's type signature (must be a tuple) * @c_handler: the signal handler function - * @data: (allow-none): data to pass to @c_handler + * @data: (nullable): data to pass to @c_handler * * Simplified version of _nm_dbus_proxy_signal_connect_data() with fewer arguments. * diff --git a/src/libnm-glib-aux/nm-dedup-multi.c b/src/libnm-glib-aux/nm-dedup-multi.c index 82f4802f3b..9cd289c34d 100644 --- a/src/libnm-glib-aux/nm-dedup-multi.c +++ b/src/libnm-glib-aux/nm-dedup-multi.c @@ -951,7 +951,7 @@ nm_dedup_multi_objs_to_ptr_array_head(const NMDedupMultiHeadEntry *head_entry, /** * nm_dedup_multi_entry_reorder: * @entry: the entry to reorder. It must not be NULL (and tracked in an index). - * @entry_order: (allow-none): an optional other entry. It MUST be in the same + * @entry_order: (nullable): an optional other entry. It MUST be in the same * list as entry. If given, @entry will be ordered after/before @entry_order. * If left at %NULL, @entry will be moved to the front/end of the list. * @order_after: if @entry_order is given, %TRUE means to move @entry after diff --git a/src/libnm-glib-aux/nm-io-utils.c b/src/libnm-glib-aux/nm-io-utils.c index ed28aabcc6..dd5ea08e32 100644 --- a/src/libnm-glib-aux/nm-io-utils.c +++ b/src/libnm-glib-aux/nm-io-utils.c @@ -79,7 +79,7 @@ _nm_printf(4, 5) static int _get_contents_error(GError **error, * the NUL byte. That is, it reads only files up to a length of * @max_length - 1 bytes. * @length: optional output argument of the read file size. - * @out_errsv: (allow-none) (out): on error, a positive errno. or zero. + * @out_errsv: (out) (optional): on error, a positive errno. or zero. * @error: * * @@ -276,7 +276,7 @@ nm_utils_fd_get_contents(int fd, * the NUL byte. That is, it reads only files up to a length of * @max_length - 1 bytes. * @length: optional output argument of the read file size. - * @out_errsv: (allow-none) (out): on error, a positive errno. or zero. + * @out_errsv: (out) (optional): on error, a positive errno. or zero. * @error: * * A reimplementation of g_file_get_contents() with a few differences: @@ -444,7 +444,7 @@ nm_utils_file_set_contents(const char *filename, /** * nm_utils_file_stat: * @filename: the filename to stat. - * @out_st: (allow-none) (out): if given, this will be passed to stat(). + * @out_st: (nullable) (out): if given, this will be passed to stat(). * * Just wraps stat() and gives the errno number as function result instead * of setting the errno (though, errno is also set). It's only for convenience diff --git a/src/libnm-glib-aux/nm-macros-internal.h b/src/libnm-glib-aux/nm-macros-internal.h index 10380bcdb9..03eff1cbf6 100644 --- a/src/libnm-glib-aux/nm-macros-internal.h +++ b/src/libnm-glib-aux/nm-macros-internal.h @@ -239,7 +239,7 @@ _nm_auto_freev(gpointer ptr) /** * NM_G_ERROR_MSG: - * @error: (allow-none): the #GError instance + * @error: (nullable): the #GError instance * * All functions must follow the convention that when they * return a failure, they must also set the GError to a valid diff --git a/src/libnm-glib-aux/nm-random-utils.c b/src/libnm-glib-aux/nm-random-utils.c index 2050d2f99a..bbc5536ae3 100644 --- a/src/libnm-glib-aux/nm-random-utils.c +++ b/src/libnm-glib-aux/nm-random-utils.c @@ -301,7 +301,7 @@ _bad_random_bytes(guint8 *buf, gsize n) * nm_random_get_bytes_full: * @p: the buffer to fill * @n: the number of bytes to write to @p. - * @out_high_quality: (allow-none) (out): whether the returned + * @out_high_quality: (out) (optional): whether the returned * random bytes are of high quality. * * - will never block diff --git a/src/libnm-glib-aux/nm-shared-utils.c b/src/libnm-glib-aux/nm-shared-utils.c index 8b255101b3..f3575074f9 100644 --- a/src/libnm-glib-aux/nm-shared-utils.c +++ b/src/libnm-glib-aux/nm-shared-utils.c @@ -439,7 +439,7 @@ nm_g_bytes_new_from_variant_ay(GVariant *var) /** * nm_g_bytes_equal_mem: - * @bytes: (allow-none): a #GBytes array to compare. Note that + * @bytes: (nullable): a #GBytes array to compare. Note that * %NULL is treated like an #GBytes array of length zero. * @mem_data: the data pointer with @mem_len bytes * @mem_len: the length of the data pointer @@ -694,7 +694,7 @@ nm_strdict_to_variant_asv(GHashTable *strdict) * nm_strquote: * @buf: the output buffer of where to write the quoted @str argument. * @buf_len: the size of @buf. - * @str: (allow-none): the string to quote. + * @str: (nullable): the string to quote. * * Writes @str to @buf with quoting. The resulting buffer * is always NUL terminated, unless @buf_len is zero. @@ -1766,11 +1766,11 @@ nm_utils_escaped_tokens_escape_full(const char *str, * nm_utils_escaped_tokens_options_split: * @str: the src string. This string will be modified in-place. * The output values will point into @str. - * @out_key: (allow-none): the returned output key. This will always be set to @str - * itself. @str will be modified to contain only the unescaped, truncated - * key name. - * @out_val: returns the parsed (and unescaped) value or %NULL, if @str contains - * no '=' delimiter. + * @out_key: (nullable) (out): the returned output key. This will always be set + * to @str itself. @str will be modified to contain only the unescaped, + * truncated key name. + * @out_val: (nullable) (out): returns the parsed (and unescaped) value or + * %NULL, if @str contains no '=' delimiter. * * Honors backslash escaping to parse @str as "key=value" pairs. Optionally, if no '=' * is present, @out_val will be returned as %NULL. Backslash can be used to escape @@ -2226,7 +2226,7 @@ nm_utils_error_is_notfound(GError *error) * @object: the target object * @property_name: the property name * @value: the #GValue to set - * @error: (allow-none): optional error argument + * @error: optional error argument * * A reimplementation of g_object_set_property(), but instead * returning an error instead of logging a warning. All g_object_set*() @@ -2526,7 +2526,7 @@ _str_buf_append_c_escape_octal(NMStrBuf *strbuf, char ch) /** * nm_utils_buf_utf8safe_unescape: - * @str: (allow-none): the string to unescape. The string itself is a NUL terminated + * @str: (nullable): the string to unescape. The string itself is a NUL terminated * ASCII string, that can have C-style backslash escape sequences (which * are to be unescaped). Non-ASCII characters (e.g. UTF-8) are taken verbatim, so * it doesn't care that this string is UTF-8. However, usually this is a UTF-8 encoded @@ -3334,9 +3334,9 @@ _utils_hashtable_equal(GHashTable *hash_a, /** * nm_utils_hashtable_cmp_equal: - * @a: (allow-none): the hash table or %NULL - * @b: (allow-none): the other hash table or %NULL - * @cmp_values: (allow-none): if %NULL, only the keys + * @a: (nullable): the hash table or %NULL + * @b: (nullable): the other hash table or %NULL + * @cmp_values: (nullable): if %NULL, only the keys * will be compared. Otherwise, this function is used to * check whether all keys are equal. * @user_data: the argument for @cmp_values. @@ -3403,8 +3403,8 @@ _hashtable_cmp_func(gconstpointer a, gconstpointer b, gpointer user_data) /** * nm_utils_hashtable_cmp: - * @a: (allow-none): the hash to compare. May be %NULL. - * @b: (allow-none): the other hash to compare. May be %NULL. + * @a: (nullable): the hash to compare. May be %NULL. + * @b: (nullable): the other hash to compare. May be %NULL. * @do_fast_precheck: if %TRUE, assume that the hashes are equal * and that it is worth calling nm_utils_hashtable_cmp_equal() first. * That requires, that both hashes have the same equals function @@ -3412,7 +3412,7 @@ _hashtable_cmp_func(gconstpointer a, gconstpointer b, gpointer user_data) * @cmp_keys: the compare function for keys. Usually, the hash/equal function * of both hashes corresponds to this function. If you set @do_fast_precheck * to false, then this is not a requirement. - * @cmp_values: (allow-none): if %NULL, only the keys are compared. + * @cmp_values: (nullable): if %NULL, only the keys are compared. * Otherwise, the values must are also compared with this function. * * Both hashes must have keys/values of the same domain, so that diff --git a/src/libnm-glib-aux/nm-str-buf.h b/src/libnm-glib-aux/nm-str-buf.h index 32ab8da840..c62381e53d 100644 --- a/src/libnm-glib-aux/nm-str-buf.h +++ b/src/libnm-glib-aux/nm-str-buf.h @@ -522,8 +522,8 @@ nm_str_buf_get_char(const NMStrBuf *strbuf, gsize index) /** * nm_str_buf_finalize: - * @strbuf: an initilized #NMStrBuf - * @out_len: (out): (allow-none): optional output + * @strbuf: an initialized #NMStrBuf + * @out_len: (out): (optional): optional output * argument with the length of the returned string. * * Returns: (transfer full): the string of the buffer diff --git a/src/libnm-glib-aux/nm-test-utils.h b/src/libnm-glib-aux/nm-test-utils.h index b65818e00a..4d99e643e9 100644 --- a/src/libnm-glib-aux/nm-test-utils.h +++ b/src/libnm-glib-aux/nm-test-utils.h @@ -1249,7 +1249,7 @@ nmtst_stable_rand(guint64 seed, gpointer buf, gsize len) /** * nmtst_get_rand_word_length: - * @rand: (allow-none): #GRand instance or %NULL to use the singleton. + * @rand: (nullable): #GRand instance or %NULL to use the singleton. * * Returns: a random integer >= 0, that most frequently is somewhere between * 0 and 16, but (with decreasing) probability, it can be larger. This can diff --git a/src/libnm-glib-aux/nm-uuid.c b/src/libnm-glib-aux/nm-uuid.c index cdfa5f629e..df1b10c0ac 100644 --- a/src/libnm-glib-aux/nm-uuid.c +++ b/src/libnm-glib-aux/nm-uuid.c @@ -411,7 +411,7 @@ nm_uuid_generate_from_string_str(const char *s, * @uuid_type: the UUID type to use. Prefer version 5 unless you have * good reasons. * @type_args: the namespace UUID. - * @strv: (allow-none): the strv list to hash. Can be NULL, in which + * @strv: (nullable): the strv list to hash. Can be NULL, in which * case the result is different from an empty array. * @len: if negative, @strv is a NULL terminated array. Otherwise, * it is the length of the strv array. In the latter case it may diff --git a/src/libnm-platform/nm-linux-platform.c b/src/libnm-platform/nm-linux-platform.c index b6c2902d20..91b6f8841a 100644 --- a/src/libnm-platform/nm-linux-platform.c +++ b/src/libnm-platform/nm-linux-platform.c @@ -4557,15 +4557,15 @@ _new_from_nl_tfilter(NMPlatform *platform, const struct nlmsghdr *nlh, gboolean /** * nmp_object_new_from_nl: - * @platform: (allow-none): for creating certain objects, the constructor wants to check + * @platform: (nullable): for creating certain objects, the constructor wants to check * sysfs. For this the platform instance is needed. If missing, the object might not * be correctly detected. - * @cache: (allow-none): for certain objects, the netlink message doesn't contain all the information. + * @cache: (nullable): for certain objects, the netlink message doesn't contain all the information. * If a cache is given, the object is completed with information from the cache. * @nlh: the netlink message header * @id_only: whether only to create an empty object with only the ID fields set. * - * Returns: %NULL or a newly created NMPObject instance. + * Returns: (nullable): %NULL or a newly created NMPObject instance. **/ static NMPObject * nmp_object_new_from_nl(NMPlatform *platform, diff --git a/src/libnm-platform/nm-netlink.c b/src/libnm-platform/nm-netlink.c index e95768465a..00b6880abb 100644 --- a/src/libnm-platform/nm-netlink.c +++ b/src/libnm-platform/nm-netlink.c @@ -1496,13 +1496,13 @@ nl_send_auto(struct nl_sock *sk, struct nl_msg *msg) * @nla: (out): the source address on success. * @buf: (out): pointer to the result buffer on success. This is * either @buf0 or an allocated buffer that gets returned. - * @out_creds: (out) (allow-none): optional out buffer for the credentials + * @out_creds: (out) (optional): optional out buffer for the credentials * on success. - * @out_creds_has: (out) (allow-none): result indicating whether + * @out_creds_has: (out) (optional): result indicating whether * @out_creds was filled. -* @out_pktinfo_group: (out) (allow-none): optional out buffer for NETLINK_PKTINFO +* @out_pktinfo_group: (out) (optional): optional out buffer for NETLINK_PKTINFO * group on success. - * @out_pktinfo_has: (out) (allow-none): result indicating whether + * @out_pktinfo_has: (out) (optional): result indicating whether * @out_pktinfo_group was filled. * * If @buf0_len is zero, the function will g_malloc() a new receive buffer of size diff --git a/src/libnm-platform/nm-platform-utils.c b/src/libnm-platform/nm-platform-utils.c index bebc53a851..8d3281dbbe 100644 --- a/src/libnm-platform/nm-platform-utils.c +++ b/src/libnm-platform/nm-platform-utils.c @@ -1955,10 +1955,10 @@ nmp_utils_ip_config_source_to_string(NMIPConfigSource source, char *buf, gsize l /** * nmp_utils_sysctl_open_netdir: * @ifindex: the ifindex for which to open "/sys/class/net/%s" - * @ifname_guess: (allow-none): optional argument, if present used as initial + * @ifname_guess: (nullable): optional argument, if present used as initial * guess as the current name for @ifindex. If guessed right, * it saves an additional if_indextoname() call. - * @out_ifname: (allow-none): if present, must be at least IFNAMSIZ + * @out_ifname: (optional): if present, must be at least IFNAMSIZ * characters. On success, this will contain the actual ifname * found while opening the directory. * diff --git a/src/libnm-platform/nm-platform.c b/src/libnm-platform/nm-platform.c index deaf72acab..d837f37411 100644 --- a/src/libnm-platform/nm-platform.c +++ b/src/libnm-platform/nm-platform.c @@ -1241,7 +1241,7 @@ _link_add_check_existing(NMPlatform *self, * @type: Interface type * @name: Interface name * @parent: the IFLA_LINK parameter or 0. - * @address: (allow-none): set the mac address of the link + * @address: (nullable): set the mac address of the link * @address_len: the length of the @address * @extra_data: depending on @type, additional data. * @out_link: on success, the link object @@ -2347,7 +2347,7 @@ nm_platform_link_can_assume(NMPlatform *self, int ifindex) * @self: the platform instance * @ifindex: the link ifindex to lookup * @link_type: filter by link-type. - * @out_link: (allow-none): returns the platform link instance + * @out_link: (out) (optional) (nullable): returns the platform link instance * * If the function returns %NULL, that could mean that no such ifindex * exists, of that the link has no lnk data. You can find that out @@ -2358,7 +2358,7 @@ nm_platform_link_can_assume(NMPlatform *self, int ifindex) * object if it is present. If you set link-type, you can be sure * that only a link type of the matching type is returned (or %NULL). * - * Returns: the internal link lnk object. The returned object + * Returns: (nullable): the internal link lnk object. The returned object * is owned by the platform cache and must not be modified. Note * however, that the object is guaranteed to be immutable, so * you can safely take a reference and keep it for yourself @@ -2616,7 +2616,7 @@ nm_platform_link_wireguard_change(NMPlatform *self * @vnet_hdr: whether to set the IFF_VNET_HDR flag * @multi_queue: whether to set the IFF_MULTI_QUEUE flag * @out_link: on success, the link object - * @out_fd: (allow-none): if give, return the file descriptor for the + * @out_fd: (out) (optional): if give, return the file descriptor for the * created device. Note that when creating a non-persistent device, * this argument is mandatory, otherwise it makes no sense * to create such an interface. @@ -3078,7 +3078,7 @@ nm_platform_link_veth_get_properties(NMPlatform *self, int ifindex, int *out_pee * nm_platform_link_tun_get_properties: * @self: the #NMPlatform instance * @ifindex: the ifindex to look up - * @out_properties: (out) (allow-none): return the read properties + * @out_properties: (out) (optional): return the read properties * * Only recent versions of kernel export tun properties via netlink. * So, if that's the case, then we have the NMPlatformLnkTun instance @@ -4099,7 +4099,7 @@ ip6_address_scope_cmp_descending(gconstpointer p_a, gconstpointer p_b, gpointer * @known_addresses: List of addresses. The list will be modified and * expired addresses will be cleared (by calling nmp_object_unref() * on the array element). - * @addresses_prune: (allow-none): the list of addresses to delete. + * @addresses_prune: (nullable): the list of addresses to delete. * If platform has such an address configured, it will be deleted * at the beginning of the sync. Note that the array will be modified * by the function. @@ -4914,14 +4914,14 @@ nm_platform_ip_route_get_prune_list(NMPlatform *self, * @self: the #NMPlatform instance. * @addr_family: AF_INET or AF_INET6. * @ifindex: the @ifindex for which the routes are to be added. - * @routes: (allow-none): a list of routes to configure. Must contain + * @routes: (nullable): a list of routes to configure. Must contain * NMPObject instances of routes, according to @addr_family. - * @routes_prune: (allow-none): the list of routes to delete. + * @routes_prune: (nullable): the list of routes to delete. * If platform has such a route configured, it will be deleted * at the end of the operation. Note that if @routes contains * the same route, then it will not be deleted. @routes overrules * @routes_prune list. - * @out_routes_failed: (allow-none) (out): routes that could + * @out_routes_failed: (out) (optional) (nullable): routes that could * not be synced/added. * * Returns: %TRUE on success. @@ -5834,7 +5834,7 @@ nm_platform_vlan_qos_mapping_to_string(const char *name, /** * nm_platform_link_to_string: * @route: pointer to NMPlatformLink address structure - * @buf: (allow-none): an optional buffer. If %NULL, a static buffer is used. + * @buf: (nullable): an optional buffer. If %NULL, a static buffer is used. * @len: the size of the @buf. If @buf is %NULL, this argument is ignored. * * A method for converting an link struct into a string representation. @@ -6822,11 +6822,11 @@ _rtm_flags_to_string_full(char *buf, gsize buf_size, unsigned rtm_flags) /** * nm_platform_ip4_route_to_string: * @route: pointer to NMPlatformIP4Route route structure - * @extra_nexthops: (allow-none): the route might be a ECMP multihop route + * @extra_nexthops: (nullable): the route might be a ECMP multihop route * (with n_nexthops > 1). In that case, provide the list of extra hops * to print too. It is allowed for a multihop route to omit the extra hops * by passing NULL. - * @buf: (allow-none): an optional buffer. If %NULL, a static buffer is used. + * @buf: (nullable): an optional buffer. If %NULL, a static buffer is used. * @len: the size of the @buf. If @buf is %NULL, this argument is ignored. * * A method for converting a route struct into a string representation. @@ -7016,7 +7016,7 @@ nm_platform_ip4_route_to_string_full(const NMPlatformIP4Route *route, /** * nm_platform_ip6_route_to_string: * @route: pointer to NMPlatformIP6Route route structure - * @buf: (allow-none): an optional buffer. If %NULL, a static buffer is used. + * @buf: (nullable): an optional buffer. If %NULL, a static buffer is used. * @len: the size of the @buf. If @buf is %NULL, this argument is ignored. * * A method for converting a route struct into a string representation. diff --git a/src/libnm-platform/nmp-object.c b/src/libnm-platform/nmp-object.c index 9ba027ba95..7e3fb1a3e8 100644 --- a/src/libnm-platform/nmp-object.c +++ b/src/libnm-platform/nmp-object.c @@ -134,7 +134,7 @@ nm_sock_addr_union_hash_update(const NMSockAddrUnion *a, NMHashState *h) * @dst: the destination #NMSockAddrUnion. It will always be fully initialized, * to one of the address families AF_INET, AF_INET6, or AF_UNSPEC (in case of * error). - * @src: (allow-none): the source buffer with an sockaddr to copy. It may be unaligned in + * @src: (nullable): the source buffer with an sockaddr to copy. It may be unaligned in * memory. If not %NULL, the buffer must be at least large enough to contain * sa.sa_family, and then, depending on sa.sa_family, it must be large enough * to hold struct sockaddr_in or struct sockaddr_in6. @@ -2047,10 +2047,10 @@ nmp_cache_link_connected_for_slave(int ifindex_master, const NMPObject *slave) * @cache: the platform cache * @master: the link object, that is checked whether its connected property * needs to be toggled. - * @potential_slave: (allow-none): an additional link object that is treated + * @potential_slave: (nullable): an additional link object that is treated * as if it was inside @cache. If given, it shaddows a link in the cache * with the same ifindex. - * @ignore_slave: (allow-none): if set, the check will pretend that @ignore_slave + * @ignore_slave: (nullable): if set, the check will pretend that @ignore_slave * is not in the cache. * * NMPlatformLink has two connected flags: (master->link.flags&IFF_LOWER_UP) (as reported @@ -2114,10 +2114,10 @@ nmp_cache_link_connected_needs_toggle(const NMPCache *cache, * @cache: * @master_ifindex: the ifindex of a potential master that should be checked * whether it needs toggling. - * @potential_slave: (allow-none): passed to nmp_cache_link_connected_needs_toggle(). + * @potential_slave: (nullable): passed to nmp_cache_link_connected_needs_toggle(). * It considers @potential_slave as being inside the cache, replacing an existing * link with the same ifindex. - * @ignore_slave: (allow-onne): passed to nmp_cache_link_connected_needs_toggle(). + * @ignore_slave: (nullable): passed to nmp_cache_link_connected_needs_toggle(). * * The flag obj->link.connected depends on the state of other links in the * @cache. See also nmp_cache_link_connected_needs_toggle(). Given an ifindex @@ -2833,11 +2833,11 @@ nmp_cache_remove_netlink(NMPCache *cache, * afterwards. Hence, during a dump, every update should move the object to the * end of the list, to obtain the correct order. That means, to use NM_DEDUP_MULTI_IDX_MODE_APPEND_FORCE, * instead of NM_DEDUP_MULTI_IDX_MODE_APPEND. - * @out_obj_old: (allow-none) (out): return the object with same ID as @obj_hand_over, - * that was in the cache before update. If an object is returned, the caller must - * unref it afterwards. - * @out_obj_new: (allow-none) (out): return the object from the cache after update. - * The caller must unref this object. + * @out_obj_old: (out) (optional) (nullable) (transfer full): return the object + * with same ID as @obj_hand_over, that was in the cache before update. If an + * object is returned, the caller must unref it afterwards. + * @out_obj_new: (out) (optional) (nullable) (transfer full): return the object + * from the cache after update. The caller must unref this object. * * Returns: how the cache changed. * diff --git a/src/libnm-platform/nmp-plobj.c b/src/libnm-platform/nmp-plobj.c index c27aa1fcf0..d3643ae1c1 100644 --- a/src/libnm-platform/nmp-plobj.c +++ b/src/libnm-platform/nmp-plobj.c @@ -373,7 +373,7 @@ nm_platform_ip6_address_get_peer(const NMPlatformIP6Address *addr) /** * nm_platform_ip4_address_to_string: * @route: pointer to NMPlatformIP4Address address structure - * @buf: (allow-none): an optional buffer. If %NULL, a static buffer is used. + * @buf: (nullable): an optional buffer. If %NULL, a static buffer is used. * @len: the size of the @buf. If @buf is %NULL, this argument is ignored. * * A method for converting an address struct into a string representation. @@ -479,7 +479,7 @@ nm_platform_ip4_address_to_string(const NMPlatformIP4Address *address, char *buf /** * nm_platform_ip6_address_to_string: * @route: pointer to NMPlatformIP6Address address structure - * @buf: (allow-none): an optional buffer. If %NULL, a static buffer is used. + * @buf: (nullable): an optional buffer. If %NULL, a static buffer is used. * @len: the size of the @buf. If @buf is %NULL, this argument is ignored. * * A method for converting an address struct into a string representation. diff --git a/src/libnmc-base/nm-secret-agent-simple.c b/src/libnmc-base/nm-secret-agent-simple.c index de3de05a84..d35ffd7975 100644 --- a/src/libnmc-base/nm-secret-agent-simple.c +++ b/src/libnmc-base/nm-secret-agent-simple.c @@ -1084,7 +1084,7 @@ get_secrets(NMSecretAgentOld *agent, * nm_secret_agent_simple_response: * @self: the #NMSecretAgentSimple * @request_id: the request ID being responded to - * @secrets: (allow-none): the array of secrets, or %NULL + * @secrets: (nullable): the array of secrets, or %NULL * * Response to a #NMSecretAgentSimple::get-secrets signal. * @@ -1252,7 +1252,7 @@ delete_secrets(NMSecretAgentOld *agent, /** * nm_secret_agent_simple_enable: * @self: the #NMSecretAgentSimple - * @path: (allow-none): the path of the connection (if any) to handle secrets + * @path: (nullable): the path of the connection (if any) to handle secrets * for. If %NULL, secrets for any connection will be handled. * * Enables servicing the requests including the already queued ones. If @path diff --git a/src/libnmt-newt/nmt-newt-form.c b/src/libnmt-newt/nmt-newt-form.c index de80b42a6c..6e0589cc5b 100644 --- a/src/libnmt-newt/nmt-newt-form.c +++ b/src/libnmt-newt/nmt-newt-form.c @@ -70,7 +70,7 @@ static void nmt_newt_form_redraw(NmtNewtForm *form); /** * nmt_newt_form_new: - * @title: (allow-none): the form title + * @title: (nullable): the form title * * Creates a new form, which will be shown centered on the screen. * Compare nmt_newt_form_new_fullscreen(). You can also position a @@ -91,7 +91,7 @@ nmt_newt_form_new(const char *title) /** * nmt_newt_form_new_fullscreen: - * @title: (allow-none): the form title + * @title: (nullable): the form title * * Creates a new fullscreen form. Compare nmt_newt_form_new(). * diff --git a/src/libnmt-newt/nmt-newt-listbox.c b/src/libnmt-newt/nmt-newt-listbox.c index 96e04c15ee..0a27e358f3 100644 --- a/src/libnmt-newt/nmt-newt-listbox.c +++ b/src/libnmt-newt/nmt-newt-listbox.c @@ -81,7 +81,7 @@ nmt_newt_listbox_new(int height, NmtNewtListboxFlags flags) * nmt_newt_listbox_append: * @listbox: an #NmtNewtListbox * @entry: the text for the new row - * @key: (allow-none): the key associated with @entry + * @key: (nullable): the key associated with @entry * * Adds a row to @listbox. */ diff --git a/src/nm-cloud-setup/nm-http-client.c b/src/nm-cloud-setup/nm-http-client.c index 49f893e281..20ef6473d6 100644 --- a/src/nm-cloud-setup/nm-http-client.c +++ b/src/nm-cloud-setup/nm-http-client.c @@ -359,8 +359,8 @@ nm_http_client_req(NMHttpClient *self, * nm_http_client_req_finish: * @self: the #NMHttpClient instance * @result: the #GAsyncResult which to complete. - * @out_response_code: (allow-none) (out): the HTTP response code or -1 on other error. - * @out_response_data: (allow-none) (transfer full): the HTTP response data, if any. + * @out_response_code: (out) (optional): the HTTP response code or -1 on other error. + * @out_response_data: (out) (optional) (nullable) (transfer full): the HTTP response data, if any. * The GBytes buffer is guaranteed to have a trailing NUL character *after* the * returned buffer size. That means, you can always trust that the buffer is NUL terminated * and that there is one additional hidden byte after the data. diff --git a/src/nm-dispatcher/nm-dispatcher.c b/src/nm-dispatcher/nm-dispatcher.c index 80fe40a0d6..97b85813dc 100644 --- a/src/nm-dispatcher/nm-dispatcher.c +++ b/src/nm-dispatcher/nm-dispatcher.c @@ -243,7 +243,7 @@ _idle_timeout_restart(void) /** * next_request: * - * @request: (allow-none): the request to set as next. If %NULL, dequeue the next + * @request: (nullable): the request to set as next. If %NULL, dequeue the next * waiting request. Otherwise, try to set the given request. * * Sets the currently active request (@current_request). The current request diff --git a/src/nmcli/connections.c b/src/nmcli/connections.c index 5de64727b3..039876c962 100644 --- a/src/nmcli/connections.c +++ b/src/nmcli/connections.c @@ -6481,11 +6481,11 @@ should_complete_cmd(const char *line, int end, const char *cmd, int *cw_num, cha /* * extract_setting_and_property: - * prompt: (in) (allow-none): prompt string, or NULL - * line: (in) (allow-none): line, or NULL - * setting: (out) (transfer full) (array zero-terminated=1): + * prompt: (nullable): prompt string, or NULL + * line: (nullable): line, or NULL + * setting: (out) (transfer full) (array zero-terminated=1) (optional): * return location for setting name - * property: (out) (transfer full) (array zero-terminated=1): + * property: (out) (transfer full) (array zero-terminated=1) (optional): * return location for property name * * Extract setting and property names from prompt and/or line. diff --git a/src/nmcli/utils.c b/src/nmcli/utils.c index 7d446cef24..5fb1ba794f 100644 --- a/src/nmcli/utils.c +++ b/src/nmcli/utils.c @@ -837,8 +837,8 @@ _output_selection_parse(const NMMetaAbstractInfo *const *fields, * @field_str: comma-separated field names to parse * @fields_array: array of allowed fields * @parse_groups: whether the fields can contain group prefix (e.g. general.driver) - * @group_fields: (out) (allow-none): array of field names for particular groups - * @error: (out) (allow-none): location to store error, or %NULL + * @group_fields: (out) (optional) (nullable): array of field names for particular groups + * @error: location to store error, or %NULL * * Parses comma separated fields in @fields_str according to @fields_array. * When @parse_groups is %TRUE, fields can be in the form 'group.field'. Then diff --git a/src/nmtui/nm-editor-utils.c b/src/nmtui/nm-editor-utils.c index 0f69c9627d..0b6c00eec0 100644 --- a/src/nmtui/nm-editor-utils.c +++ b/src/nmtui/nm-editor-utils.c @@ -367,7 +367,7 @@ get_available_iface_name(const char *try_name, NMClient *client) /** * nm_editor_utils_create_connection: * @type: the type of the connection's primary #NMSetting - * @master: (allow-none): the connection's master, if any + * @master: (nullable): the connection's master, if any * @client: an #NMClient * * Creates a new #NMConnection of the given type, automatically diff --git a/src/nmtui/nmt-editor-grid.c b/src/nmtui/nmt-editor-grid.c index e3524084fd..9b76e3fe22 100644 --- a/src/nmtui/nmt-editor-grid.c +++ b/src/nmtui/nmt-editor-grid.c @@ -85,9 +85,9 @@ nmt_editor_grid_finalize(GObject *object) /** * nmt_editor_grid_append: * @grid: the #NmtEditorGrid - * @label: (allow-none): the label text for @widget, or %NULL - * @widget: (allow-none): the (main) widget - * @extra: (allow-none): optional extra widget + * @label: (nullable): the label text for @widget, or %NULL + * @widget: (nullable): the (main) widget + * @extra: (nullable): optional extra widget * * Adds a row to @grid. * diff --git a/src/nmtui/nmt-editor-section.c b/src/nmtui/nmt-editor-section.c index 462d1f89fa..0f8aa6e001 100644 --- a/src/nmtui/nmt-editor-section.c +++ b/src/nmtui/nmt-editor-section.c @@ -42,7 +42,7 @@ enum { /** * nmt_editor_section_new: * @title: the section title - * @header_widget: (allow-none): the widget to show next to the title + * @header_widget: (nullable): the widget to show next to the title * @show_by_default: whether the section should be open by default * * Creates a new #NmtEditorSection. diff --git a/src/nmtui/nmt-slave-list.c b/src/nmtui/nmt-slave-list.c index b3ba8dc4ca..c523f305e5 100644 --- a/src/nmtui/nmt-slave-list.c +++ b/src/nmtui/nmt-slave-list.c @@ -44,8 +44,8 @@ static gboolean nmt_slave_list_connection_filter(NmtEditConnectionList *list, /** * nmt_slave_list_new: * @master: the master #NMConnection whose slaves are being listed - * @type_filter: (allow-none): a function to limit the available slave types - * @type_filter_data: (allow-none): data for @type_filter. + * @type_filter: (nullable): a function to limit the available slave types + * @type_filter_data: (nullable): data for @type_filter. * * Creates a new #NmtSlaveList. * diff --git a/src/nmtui/nmt-utils.c b/src/nmtui/nmt-utils.c index 84d9e9bbbf..7a50054258 100644 --- a/src/nmtui/nmt-utils.c +++ b/src/nmtui/nmt-utils.c @@ -78,7 +78,7 @@ nmt_sync_op_wait_boolean(NmtSyncOp *op, GError **error) * nmt_sync_op_complete_boolean: * @op: the #NmtSyncOp * @result: the result of the operation - * @error: (allow-none): the error, or %NULL + * @error: (nullable): the error, or %NULL * * Completes @op and returns @result and/or @error to the caller. */ @@ -115,7 +115,7 @@ nmt_sync_op_wait_pointer(NmtSyncOp *op, GError **error) * nmt_sync_op_complete_pointer: * @op: the #NmtSyncOp * @result: the result of the operation - * @error: (allow-none): the error, or %NULL + * @error: (nullable): the error, or %NULL * * Completes @op and returns @result and/or @error to the caller. */ diff --git a/src/nmtui/nmt-widget-list.c b/src/nmtui/nmt-widget-list.c index 18d4d16e3b..d150eee081 100644 --- a/src/nmtui/nmt-widget-list.c +++ b/src/nmtui/nmt-widget-list.c @@ -95,7 +95,7 @@ static void remove_clicked(NmtNewtButton *button, gpointer user_data); * @create_callback: callback to create new widgets * @user_data: user data for @create_callback * @destroy_notify: #GDestroyNotify for @user_data - * @empty_widget: (allow-none): a widget to display when there are + * @empty_widget: (nullable): a widget to display when there are * no "real" widgets in the list. * * Creates a new #NmtWidgetList. |