From: Peter Maydell <peter.maydell@linaro.org>

We don't document qdev_get_dev_path() at all; in particular
we do not mention that it returns a string that the caller
must free.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20260307155046.3940197-2-peter.maydell@linaro.org>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 include/hw/core/qdev.h | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/include/hw/core/qdev.h b/include/hw/core/qdev.h
index 4b2730e9d8e..29083bc9078 100644
--- a/include/hw/core/qdev.h
+++ b/include/hw/core/qdev.h
@@ -324,6 +324,10 @@ struct BusClass {
 
     /* FIXME first arg should be BusState */
     void (*print_dev)(Monitor *mon, DeviceState *dev, int indent);
+    /*
+     * Return a newly allocated string containing the path of the
+     * device on this bus.
+     */
     char *(*get_dev_path)(DeviceState *dev);
 
     /*
@@ -1060,6 +1064,25 @@ bool qdev_set_parent_bus(DeviceState *dev, BusState *bus, Error **errp);
 
 extern bool qdev_hot_removed;
 
+/**
+ * qdev_get_dev_path(): Return the path of a device on its bus
+ * @dev: device to get the path of
+ *
+ * Returns: A newly allocated string containing the dev path of
+ * @dev. The caller must free this with g_free().
+ * The format of the string depends on the bus; for instance a
+ * PCI device's path will be in the format::
+ *
+ *   Domain:00:Slot.Function:Slot.Function....:Slot.Function
+ *
+ * and a SCSI device's path will be::
+ *
+ *   channel:ID:LUN
+ *
+ * (possibly prefixed by the path of the SCSI controller).
+ *
+ * If @dev is NULL or not on a bus, returns NULL.
+ */
 char *qdev_get_dev_path(DeviceState *dev);
 const char *qdev_get_printable_name(DeviceState *dev);
 
-- 
2.53.0