Re: [PATCH v3 01/46] net: add qemu_{configure,create}_nic_device(), qemu_find_nic_info()

[David Woodhouse]

On Fri, 2024-01-26 at 14:43 +0000, Peter Maydell wrote:
> 
> > +NICInfo *qemu_find_nic_info(const char *typename, bool match_default,
> > +                            const char *alias);
> > +bool qemu_configure_nic_device(DeviceState *dev, bool match_default,
> > +                               const char *alias);
> > +DeviceState *qemu_create_nic_device(const char *typename, bool 
> > match_default,
> > +                                    const char *alias);
> 
> Could we have doc comments that document the purpose and API
> for these new global functions, please?

Like this? I deliberately fatfingered the argument names and didn't
even get a build warning, and I don't see any actual *documentation*
being generated with it...?

diff --git a/include/net/net.h b/include/net/net.h
index 25ea83fd12..14614b0a31 100644
--- a/include/net/net.h
+++ b/include/net/net.h
@@ -207,10 +207,46 @@ int qemu_show_nic_models(const char *arg, const char 
*const *models);
 void qemu_check_nic_model(NICInfo *nd, const char *model);
 int qemu_find_nic_model(NICInfo *nd, const char * const *models,
                         const char *default_model);
+/**
+ * qemu_find_nic_info: Obtain NIC configuration information
+ * @typename: Name of device object type
+ * @match_default: Match NIC configurations with no model specified
+ * @alias: Additional model string to match (for user convenience and
+ *         backward compatibility).
+ *
+ * Search for a NIC configuration matching the NIC model constraints.
+ */
 NICInfo *qemu_find_nic_info(const char *typename, bool match_default,
                             const char *alias);
+/**
+ * qemu_configure_nic_device: Apply NIC configuration to a given device
+ * @dev: Network device to be configured
+ * @match_default: Match NIC configurations with no model specified
+ * @alias: Additional model string to match
+ *
+ * Search for a NIC configuration for the provided device, using the
+ * additionally specified matching constraints. If found, apply the
+ * configuration using qdev_set_nic_properties() and return %true.
+ *
+ * This is used by platform code which creates the device anyway,
+ * regardless of whether there is a configuration for it. This tends
+ * to be platforms which ignore `--nodefaults` and create net devices
+ * anyway. This behaviour is not advised for new platforms; use the
+ * qemu_create_nic_device() function instead, which creates the device
+ * only when it is configured.
+ */
 bool qemu_configure_nic_device(DeviceState *dev, bool match_default,
                                const char *alias);
+
+/**
+ * qemu_create_nic_device: Create a NIC device if a configuration exists for it
+ * @typename: Object typename of network device
+ * @match_default: Match NIC configurations with no model specified
+ * @alias: Additional model string to match
+ *
+ * Search for a NIC configuration for the provided device type. If found,
+ * create an object of the corresponding type and return it.
+ */
 DeviceState *qemu_create_nic_device(const char *typename, bool match_default,
                                     const char *alias);
 void print_net_client(Monitor *mon, NetClientState *nc);

smime.p7s
Description: S/MIME cryptographic signature