[qemu-xen staging] qemu-common: Document qemu_find_file()

[patchbot@xxxxxxx]

commit b6c61f69349ca3706c7e757ec1f2df916b70de7a
Author:     Philippe Mathieu-Daudé <f4bug@xxxxxxxxx>
AuthorDate: Tue Jul 14 18:10:10 2020 +0200
Commit:     Philippe Mathieu-Daudé <f4bug@xxxxxxxxx>
CommitDate: Tue Jul 21 16:13:04 2020 +0200

    qemu-common: Document qemu_find_file()
    
    Document qemu_find_file(), in particular the returned
    value which must be freed.
    
    Signed-off-by: Philippe Mathieu-Daudé <f4bug@xxxxxxxxx>
    Reviewed-by: Peter Maydell <peter.maydell@xxxxxxxxxx>
    Reviewed-by: Li Qiang <liq3ea@xxxxxxxxx>
    Reviewed-by: Michael Rolnik <mrolnik@xxxxxxxxx>
    Tested-by: Michael Rolnik <mrolnik@xxxxxxxxx>
    Reviewed-by: Daniel P. Berrangé <berrange@xxxxxxxxxx>
    Message-Id: <20200714164257.23330-4-f4bug@xxxxxxxxx>
---
 include/qemu-common.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/include/qemu-common.h b/include/qemu-common.h
index d0142f29ac..bb9496bd80 100644
--- a/include/qemu-common.h
+++ b/include/qemu-common.h
@@ -110,6 +110,23 @@ const char *qemu_get_vm_name(void);
 
 #define QEMU_FILE_TYPE_BIOS   0
 #define QEMU_FILE_TYPE_KEYMAP 1
+/**
+ * qemu_find_file:
+ * @type: QEMU_FILE_TYPE_BIOS (for BIOS, VGA BIOS)
+ *        or QEMU_FILE_TYPE_KEYMAP (for keymaps).
+ * @name: Relative or absolute file name
+ *
+ * If @name exists on disk as an absolute path, or a path relative
+ * to the current directory, then returns @name unchanged.
+ * Otherwise searches for @name file in the data directories, either
+ * configured at build time (DATADIR) or registered with the -L command
+ * line option.
+ *
+ * The caller must use g_free() to free the returned data when it is
+ * no longer required.
+ *
+ * Returns: a path that can access @name, or NULL if no matching file exists.
+ */
 char *qemu_find_file(int type, const char *name);
 
 /* OS specific functions */
--
generated by git-patchbot for /home/xen/git/qemu-xen.git#staging