libvirt-qemu: Add reference to QEMU agent protocol syntax

Add a reference to the expected format of commands used with
'virDomainQemuAgentCommand'.

Closes: https://gitlab.com/libvirt/libvirt/-/work_items/891
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c
index c4cbc49ef78332eb564c93827ffc84910ebde043..3df33609e93b977adf8e9fff0009161a0709c77b 100644 (file)
--- a/src/libvirt-qemu.c
+++ b/src/libvirt-qemu.c
@@ -278,6 +278,11 @@ virDomainQemuAttach(virConnectPtr conn,
  * Execute an arbitrary Guest Agent command.
  *
  * Issue @cmd to the guest agent running in @domain.
+ *
+ * The QEMU guest agent expects the command @cmd to be in the QEMU Guest Agent
+ * Protocol format documented at:
+ * https://www.qemu.org/docs/master/interop/qemu-ga-ref.html
+ *
  * @timeout must be -2, -1, 0 or positive.
  * VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK(-2): meaning to block forever waiting for
  * a result.
@@ -285,7 +290,8 @@ virDomainQemuAttach(virConnectPtr conn,
  * VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT(0): does not wait.
  * positive value: wait for @timeout seconds
  *
- * Returns strings if success, NULL in failure.
+ * Returns string containing the verbatim reply from the guest agent on
+ * success, NULL on failure.
  *
  * Since: 0.10.0
  */