Document why this function exists and meaning of return values.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
 src/qemu/qemu_domain.c | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
index 9bbad887e0..8fe1b1924d 100644
--- a/src/qemu/qemu_domain.c
+++ b/src/qemu/qemu_domain.c
@@ -12368,6 +12368,18 @@ qemuDomainRemoveLogs(virQEMUDriver *driver,
 }


+/**
+ * qemuDomainObjWait:
+ * @vm: domain object
+ *
+ * Wait for a signal on the main domain condition. Take into account internal
+ * qemu state in addition to what virDomainObjWait checks. Code in the qemu
+ * driver must use this function exclusively instead of virDomainObjWait.
+ *
+ * Returns:
+ *  - 0 on successful wait AND VM is guaranteed to be running
+ *  - -1 on failure to wait or VM was terminated while waiting
+ */
 int
 qemuDomainObjWait(virDomainObj *vm)
 {
-- 
2.45.2

On 6/13/24 17:11, Peter Krempa wrote:
> Document why this function exists and meaning of return values.
> 
> Signed-off-by: Peter Krempa <pkrempa@redhat.com>
> ---
>  src/qemu/qemu_domain.c | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
> index 9bbad887e0..8fe1b1924d 100644
> --- a/src/qemu/qemu_domain.c
> +++ b/src/qemu/qemu_domain.c
> @@ -12368,6 +12368,18 @@ qemuDomainRemoveLogs(virQEMUDriver *driver,
>  }
> 
> 
> +/**
> + * qemuDomainObjWait:
> + * @vm: domain object
> + *
> + * Wait for a signal on the main domain condition. Take into account internal
> + * qemu state in addition to what virDomainObjWait checks. Code in the qemu
> + * driver must use this function exclusively instead of virDomainObjWait.
> + *
> + * Returns:
> + *  - 0 on successful wait AND VM is guaranteed to be running
> + *  - -1 on failure to wait or VM was terminated while waiting

Nitpick, drop those leading '-' symbols. And possibly add a comma/full
stop at EOLs.

> + */
>  int
>  qemuDomainObjWait(virDomainObj *vm)
>  {

Michal