all: various fixes to gtk-doc annotations

- drop annotations from "@error" which has defaults.

- ensure all annotations are on the same line. That's useful
  when searching for an annotation, to find the line that specifies
  the argument name.

- convert a few plain docs into gtkdoc annotations.

src/core/devices/nm-device.c

@@ -8453,7 +8453,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.
@@ -16725,7 +16725,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:

src/core/nm-manager.c

@@ -3902,7 +3902,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.

src/libnm-core-impl/nm-connection.c

@@ -766,11 +766,11 @@ 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>)
+ * @out_settings: (out) (element-type utf8 GLib.HashTable<utf8,uint32>) (optional) (nullable):
- * (optional) (nullable): if the connections differ, on return a hash table
+ *   if the connections differ, on return a hash table
- * mapping setting names to second-level GHashTable (utf8 to guint32), which
+ *   mapping setting names to second-level GHashTable (utf8 to guint32), which
- * contains the key names that differ mapped to one or more of
+ *   contains the key names that differ mapped to one or more of
- * %NMSettingDiffResult as a bitfield
+ *   %NMSettingDiffResult as a bitfield
  *
  * Compares two #NMConnection objects for similarity, with comparison behavior
  * modified by a set of flags.  See nm_setting_compare() for a description of
@@ -787,11 +787,11 @@ 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&lt;utf8,uint32&gt;)
+ * @out_settings: (out) (element-type utf8 GLib.HashTable&lt;utf8,uint32&gt;) (optional) (nullable):
- * (optional) (nullable): if the connections differ, on return a hash table
+ *   if the connections differ, on return a hash table
- * mapping setting names to second-level GHashTable (utf8 to guint32), which
+ *   mapping setting names to second-level GHashTable (utf8 to guint32), which
- * contains the key names that differ mapped to one or more of
+ *   contains the key names that differ mapped to one or more of
- * %NMSettingDiffResult as a bitfield
+ *   %NMSettingDiffResult as a bitfield
  *
  * Compares two #NMConnection objects for similarity, with comparison behavior
  * modified by a set of flags.  See nm_setting_compare() for a description of

src/nmcli/connections.c

@@ -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
+ * find_device_for_connection:
- *      iface:       device interface name to use (optional)
+ * @nmc: the #NmCli
- *      ap:          access point to use (optional; valid just for 802-11-wireless)
+ * @connection: connection to activate
- *      nsp:         Network Service Provider to use (option; valid only for wimax)
+ * @iface: device interface name to use (optional)
- * OUT: device:      found device
+ * @ap: access point to use (optional; valid just for 802-11-wireless)
- *      spec_object: specific_object path of NMAccessPoint
+ * @nsp: Network Service Provider to use (option; valid only for wimax)
- * RETURNS: TRUE when a device is found, FALSE otherwise.
+ * @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
+ * @prompt: (nullable): prompt string, or NULL
- * line: (nullable): line, or NULL
+ * @line: (nullable): line, or NULL
- * setting: (out) (transfer full) (array zero-terminated=1) (optional):
+ * @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)
 {