fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2026-04-28 17:00:45 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

libnm,doc: merge branch 'th/gtkdoc-annotations-cleanup'

Browse source 
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1587
This commit is contained in:
Thomas Haller 2023-03-29 11:46:01 +02:00
commit e3eaccd722
No known key found for this signature in database
GPG key ID: 29C2366E4DFC5728
14 changed files with 62 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
contrib/scripts/checkpatch.pl
View file

@ -191,6 +191,7 @@ complain ("Don't use space inside elvis operator ?:") if $line =~ /\?[\t ]+:/;
complain ("Don't add Emacs editor formatting hints to source files") if $line_no == 1 and $line =~ /-\*-.+-\*-/;
complain ("XXX marker are reserved for development while work-in-progress. Use TODO or FIXME comment instead?") if $line =~ /\bXXX\b/;
complain ("This gtk-doc annotation looks wrong") if $line =~ /\*.*\( *(transfer-(none|container|full)|allow none) *\) *(:|\()/;
complain ("The gtk-doc annotation (allow-none) is deprecated. Use either (nullable) and/or (optional). See https://gi.readthedocs.io/en/latest/annotations/giannotations.html#deprecated-gobject-introspection-annotations") if $line =~ /\*.*\( *(allow-none) *\) *(:|\()/;
complain ("Prefer nm_assert() or g_return*() to g_assert*()") if $line =~ /g_assert/ and (not $filename =~ /\/tests\//) and (not $filename =~ /\/nm-test-/);
complain ("Use gs_free_error with GError variables") if $line =~ /\bgs_free\b +GError *\*/;
complain ("Initialize GError variables to NULL, if you pass them on") if $line =~ /\bGError +\*([a-z0-9_]+);/;

6
src/core/devices/nm-device.c
View file

@ -8580,7 +8580,7 @@ device_has_config(NMDevice *self)
* @self: the master #NMDevice
* @slave: the slave #NMDevice
* @connection: the #NMConnection to update with the slave settings
* @GError: (out): error description
* @error: error description
*
* Reads the slave configuration for @slave and updates @connection with those
* properties. This invokes a virtual function on the master device @self.
@ -13000,7 +13000,7 @@ reapply_connection(NMDevice *self, NMConnection *con_old, NMConnection *con_new)
* Change configuration of an already configured device if possible.
* Updates the device's applied connection upon success.
*
* Return: %FALSE if the new configuration can not be reapplied.
* Returns: %FALSE if the new configuration can not be reapplied.
*/
static gboolean
check_and_reapply_connection(NMDevice *self,
@ -16866,7 +16866,7 @@ nm_device_hw_addr_set(NMDevice *self, const char *addr, const char *detail, gboo
* @hwaddr: (out): the cloned MAC address to set on interface
* @hwaddr_type: (out): the type of address to set
* @hwaddr_detail: (out): the detail (origin) of address to set
* @error: (out): on return, an error or %NULL
* @error: on return, an error or %NULL
*
* Computes the MAC to be set on a interface. On success, one of the
* following exclusive conditions are verified:

2
src/core/nm-manager.c
View file

@ -3905,7 +3905,7 @@ _device_realize_finish(NMManager *self, NMDevice *device, const NMPlatformLink *
* add_device:
* @self: the #NMManager
* @device: the #NMDevice to add
* @error: (out): the #GError
* @error: the #GError
*
* If successful, this function will increase the references count of @device.
* Callers should decrease the reference count.

16
src/libnm-client-impl/nm-client.c
View file

@ -4465,8 +4465,8 @@ nm_client_connectivity_check_get_uri(NMClient *client)
/**
* nm_client_get_logging:
* @client: a #NMClient
* @level: (nullable) (out) (optional): return location for logging level string
* @domains: (nullable) (out) (optional): return location for log domains string. The string is
* @level: (out) (optional) (nullable): return location for logging level string
* @domains: (out) (optional) (nullable): return location for log domains string. The string is
* a list of domains separated by ","
* @error: return location for a #GError, or %NULL
*
@ -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: (optional) (nullable) (transfer full) (out): the output result
* @out_result: (out) (optional) (nullable) (transfer full): the output result
* of type "a{sv}" returned by D-Bus' AddAndActivate2 call. Currently, no
* output is implemented yet.
*
@ -5875,7 +5875,7 @@ nm_client_add_connection2(NMClient *client,
* nm_client_add_connection2_finish:
* @client: the #NMClient
* @result: the #GAsyncResult
* @out_result: (optional) (nullable) (transfer full) (out): the output
* @out_result: (out) (optional) (nullable) (transfer full): 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.
@ -6052,7 +6052,7 @@ nm_client_load_connections_finish(NMClient *client,
* files from disk, adding, updating, and removing connections until
* the in-memory state matches the on-disk state.
*
* Return value: %TRUE on success, %FALSE on failure
* Returns: %TRUE on success, %FALSE on failure
*
* Deprecated: 1.22: Use nm_client_reload_connections_async() or GDBusConnection.
**/
@ -6125,7 +6125,7 @@ nm_client_reload_connections_async(NMClient *client,
*
* Gets the result of an nm_client_reload_connections_async() call.
*
* Return value: %TRUE on success, %FALSE on failure
* Returns: %TRUE on success, %FALSE on failure
**/
gboolean
nm_client_reload_connections_finish(NMClient *client, GAsyncResult *result, GError **error)
@ -6151,7 +6151,7 @@ nm_client_reload_connections_finish(NMClient *client, GAsyncResult *result, GErr
*
* Gets the current DNS processing mode.
*
* Return value: the DNS processing mode, or %NULL in case the
* Returns: the DNS processing mode, or %NULL in case the
* value is not available.
*
* Since: 1.6
@ -6170,7 +6170,7 @@ nm_client_get_dns_mode(NMClient *client)
*
* Gets the current DNS resolv.conf manager.
*
* Return value: the resolv.conf manager or %NULL in case the
* Returns: the resolv.conf manager or %NULL in case the
* value is not available.
*
* Since: 1.6

4
src/libnm-core-impl/nm-connection.c
View file

@ -764,8 +764,8 @@ diff_one_connection(NMConnection *a,
* @a: a #NMConnection
* @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) (nullable): if the connections differ, on return a hash table
* @out_settings: (out) (element-type utf8 GLib.HashTable(utf8,uint32)) (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

4
src/libnm-core-impl/nm-setting-wired.c
View file

@ -507,10 +507,10 @@ 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: (optional) (nullable) (out) (transfer none): on return, the key
* @out_key: (out) (optional) (nullable) (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
* @out_value: (out) (optional) (nullable) (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
*

4
src/libnm-core-impl/nm-setting.c
View file

@ -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: (nullable) (out): the optional output value.
* @out_value: (out) (nullable): 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: (nullable) (out): the optional output value.
* @out_value: (out) (nullable): the optional output value.
* If the option is unset, 0 will be returned.
*
* Returns: %TRUE if @opt_name is set to a uint32 variant.

26
src/libnm-core-impl/nm-utils.c
View file

@ -3597,7 +3597,7 @@ _nm_property_variant_to_gvalue(GVariant *src_value, GValue *dst_value)
* Before 1.28, it was an error to call this function with any value other than
* <literal>ARPHRD_ETHER</literal> or <literal>ARPHRD_INFINIBAND</literal>.
*
* Return value: the length or zero if the type is unrecognized.
* Returns: the length or zero if the type is unrecognized.
*/
gsize
nm_utils_hwaddr_len(int type)
@ -3621,7 +3621,7 @@ nm_utils_hwaddr_len(int type)
* eg "00:11" or "0:1". Any "0x" at the beginning of @hex is ignored. @hex
* may not start or end with ':'.
*
* Return value: (transfer full): the converted bytes, or %NULL on error
* Returns: (transfer full): the converted bytes, or %NULL on error
*/
GBytes *
nm_utils_hexstr2bin(const char *hex)
@ -3644,7 +3644,7 @@ nm_utils_hexstr2bin(const char *hex)
* Parses @asc and converts it to binary form in a #GByteArray. See
* nm_utils_hwaddr_aton() if you don't want a #GByteArray.
*
* Return value: (transfer full): a new #GByteArray, or %NULL if @asc couldn't
* Returns: (transfer full): a new #GByteArray, or %NULL if @asc couldn't
* be parsed
*/
GByteArray *
@ -3676,7 +3676,7 @@ fail:
* Parses @asc and converts it to binary form in @buffer.
* Bytes in @asc can be separated by colons (:), or hyphens (-), but not mixed.
*
* Return value: @buffer, or %NULL if @asc couldn't be parsed
* Returns: @buffer, or %NULL if @asc couldn't be parsed
* or would be shorter or longer than @length.
*/
guint8 *
@ -3699,7 +3699,7 @@ nm_utils_hwaddr_aton(const char *asc, gpointer buffer, gsize length)
* greater than -1, the returned string is terminated at that index
* (returned_string[final_len] == '\0'),
*
* Return value: (transfer full): the textual form of @bytes
* Returns: (transfer full): the textual form of @bytes
*/
char *
nm_utils_bin2hexstr(gconstpointer src, gsize len, int final_len)
@ -3720,7 +3720,7 @@ nm_utils_bin2hexstr(gconstpointer src, gsize len, int final_len)
*
* Converts @addr to textual form.
*
* Return value: (transfer full): the textual form of @addr
* Returns: (transfer full): the textual form of @addr
*/
char *
nm_utils_hwaddr_ntoa(gconstpointer addr, gsize length)
@ -3740,7 +3740,7 @@ nm_utils_hwaddr_ntoa(gconstpointer addr, gsize length)
* Parses @asc to see if it is a valid hardware address of the given
* length.
*
* Return value: %TRUE if @asc appears to be a valid hardware address
* Returns: %TRUE if @asc appears to be a valid hardware address
* of the indicated length, %FALSE if not.
*/
gboolean
@ -3771,7 +3771,7 @@ nm_utils_hwaddr_valid(const char *asc, gssize length)
* length, and if so, returns it in canonical form (uppercase, with
* leading 0s as needed, and with colons rather than hyphens).
*
* Return value: (transfer full): the canonicalized address if @asc appears to
* Returns: (transfer full): the canonicalized address if @asc appears to
* be a valid hardware address of the indicated length, %NULL if not.
*/
char *
@ -3832,7 +3832,7 @@ _nm_utils_ipaddr_canonical_or_invalid(int addr_family, const char *ip, gboolean
/*
* Determine if given Ethernet address is link-local
*
* Return value: %TRUE if @mac is link local
* Returns: %TRUE if @mac is link local
* reserved addr (01:80:c2:00:00:0X) per IEEE 802.1Q 8.6.3 Frame filtering, %FALSE if not.
*/
gboolean
@ -3889,7 +3889,7 @@ _nm_utils_hwaddr_link_local_valid(const char *mac)
* sanity-checked before comparing them against known good addresses; they are
* guaranteed to not match if they are invalid.)
*
* Return value: %TRUE if @hwaddr1 and @hwaddr2 are equivalent, %FALSE if they are
* Returns: %TRUE if @hwaddr1 and @hwaddr2 are equivalent, %FALSE if they are
* different (or either of them is invalid).
*/
gboolean
@ -4431,7 +4431,7 @@ nm_utils_inet6_ntop(const struct in6_addr *in6addr, char *dst)
*
* Checks if @ip contains a valid IP address of the given family.
*
* Return value: %TRUE or %FALSE
* Returns: %TRUE or %FALSE
*/
gboolean
nm_utils_ipaddr_valid(int family, const char *ip)
@ -4448,7 +4448,7 @@ nm_utils_ipaddr_valid(int family, const char *ip)
* Checks if @duid string contains either a special duid value ("ll",
* "llt", "lease" or the "stable" variants) or a valid hex DUID.
*
* Return value: %TRUE or %FALSE
* Returns: %TRUE or %FALSE
*/
gboolean
_nm_utils_dhcp_duid_valid(const char *duid, GBytes **out_duid_bin)
@ -5333,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: (optional): (out): an optional output buffer for the binary
* @out_key: (out) (optional): an optional output buffer for the binary
* key. If given, it will be filled with exactly @required_key_len
* bytes.
*

2
src/libnm-glib-aux/nm-dedup-multi.c
View file

@ -420,7 +420,7 @@ nm_dedup_multi_index_add(NMDedupMultiIndex *self,
*
* Adds and object to the index.
*
* Return: %TRUE if anything changed, %FALSE if nothing changed.
* Returns: %TRUE if anything changed, %FALSE if nothing changed.
*/
gboolean
nm_dedup_multi_index_add_full(NMDedupMultiIndex *self,

2
src/libnm-glib-aux/nm-io-utils.c
View file

@ -444,7 +444,7 @@ nm_utils_file_set_contents(const char *filename,
/**
* nm_utils_file_stat:
* @filename: the filename to stat.
* @out_st: (nullable) (out): if given, this will be passed to stat().
* @out_st: (out) (nullable): 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

8
src/libnm-glib-aux/nm-shared-utils.c
View file

@ -66,7 +66,7 @@ nm_ether_addr_from_string(NMEtherAddr *addr, const char *str)
*
* Checks if only the bottom 64bits of the address are set.
*
* Return value: %TRUE or %FALSE
* Returns: %TRUE or %FALSE
*/
gboolean
_nm_utils_inet6_is_token(const struct in6_addr *in6addr)
@ -1766,10 +1766,10 @@ 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: (nullable) (out): the returned output key. This will always be set
* @out_key: (out) (nullable): 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
* @out_val: (out) (nullable): 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 '='
@ -6775,7 +6775,7 @@ valid_ldh_char(char c)
* @s: the hostname to check.
* @trailing_dot: Accept trailing dot on multi-label names.
*
* Return: %TRUE if valid.
* Returns: %TRUE if valid.
*/
gboolean
nm_hostname_is_valid(const char *s, gboolean trailing_dot)

2
src/libnm-glib-aux/nm-shared-utils.h
View file

@ -2719,7 +2719,7 @@ guint8 *nm_utils_hexstr2bin_alloc(const char *hexstr,
* can parse addresses of any length. That is, you don't need
* to know the length before-hand.
*
* Return value: @buffer, or %NULL if @asc couldn't be parsed.
* Returns: @buffer, or %NULL if @asc couldn't be parsed.
*/
static inline guint8 *
_nm_utils_hwaddr_aton(const char *asc, gpointer buffer, gsize buffer_length, gsize *out_length)

2
src/libnmt-newt/nmt-newt-widget.c
View file

@ -171,7 +171,7 @@ nmt_newt_widget_get_components(NmtNewtWidget *widget)
*
* Finds the widget inside @widget that owns @co.
*
* Return value: @co's owner, or %NULL if it was not found.
* Returns: @co's owner, or %NULL if it was not found.
*/
NmtNewtWidget *
nmt_newt_widget_find_component(NmtNewtWidget *widget, newtComponent co)

38
src/nmcli/connections.c
View file

@ -2609,15 +2609,21 @@ get_default_active_connection(NmCli *nmc, NMDevice **device)
return default_ac;
}
/* Find a device to activate the connection on.
* IN: connection: connection to activate
* iface: device interface name to use (optional)
* ap: access point to use (optional; valid just for 802-11-wireless)
* nsp: Network Service Provider to use (option; valid only for wimax)
* OUT: device: found device
* spec_object: specific_object path of NMAccessPoint
* RETURNS: TRUE when a device is found, FALSE otherwise.
*/
/**
* find_device_for_connection:
* @nmc: the #NmCli
* @connection: connection to activate
* @iface: device interface name to use (optional)
* @ap: access point to use (optional; valid just for 802-11-wireless)
* @nsp: Network Service Provider to use (option; valid only for wimax)
* @device: (out): found device
* @spec_object: (out): specific_object path of NMAccessPoint
* @error: the error reason.
*
* Find a device to activate the connection on.
*
* Return: TRUE when a device is found, FALSE otherwise.
**/
static gboolean
find_device_for_connection(NmCli *nmc,
NMConnection *connection,
@ -6479,17 +6485,17 @@ should_complete_cmd(const char *line, int end, const char *cmd, int *cw_num, cha
return ret;
}
/*
/**
* extract_setting_and_property:
* prompt: (nullable): prompt string, or NULL
* line: (nullable): line, or NULL
* setting: (out) (transfer full) (array zero-terminated=1) (optional):
* @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) (optional):
* @property: (out) (transfer full) (array zero-terminated=1) (optional):
* return location for property name
*
* Extract setting and property names from prompt and/or line.
*/
**/
static void
extract_setting_and_property(const char *prompt, const char *line, char **setting, char **property)
{
@ -7555,7 +7561,7 @@ confirm_quit(const NmcConfig *nmc_config)
/*
* Submenu for detailed property editing
* Return: TRUE - continue; FALSE - should quit
* Returns TRUE for continue; FALSE for should quit.
*/
static gboolean
property_edit_submenu(NmCli *nmc,