qemu_api: doc improvements

The new doc text had a few readability issues.  Also, the
monitor command text copied a bit too much from the attach case.

* src/libvirt-qemu.c (virDomainQemuMonitorCommand)
(virDomainQemuAttach): Fix typos and grammar.

diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c
index b46868f713f230be1655759aa9ed7e5f008c39f2..248cc33fe49afb3e84b9ff3971cc0d7228c9bccf 100644 (file)
--- a/src/libvirt-qemu.c
+++ b/src/libvirt-qemu.c
@@ -43,32 +43,27 @@
  * @result: a string returned by @cmd
  * @flags: bitwise-or of supported virDomainQemuMonitorCommandFlags
  *
- * This API is QEMU specific, so will only work with hypervisor
+ * This API is QEMU specific, so it will only work with hypervisor
  * connections to the QEMU driver.
  *
  * Send an arbitrary monitor command @cmd to @domain through the
  * qemu monitor. There are several requirements to safely and
- * succcesfully to use this API:
+ * successfully use this API:
  *
- *   - It must have been started with a monitor socket using the UNIX
- *     domain socket protocol.
- *   - No other operations which are changing the domain state or
- *     configuration at the same time, e.g. domain saving, it might
- *     cause libvirtd crashed.
- *   - If the @cmd is intend to change domain configuration, it must
- *     be no or other configuration changes can have been made via
- *     the monitor since it started.
- *   - The '-name' and '-uuid' arguments should have been set (not
- *     mandatory, but strongly recommended)
+ *   - A @cmd that queries state without making any modifications is safe
+ *   - A @cmd that alters state that is also tracked by libvirt is unsafe,
+ *     and may cause libvirtd to crash
+ *   - A @cmd that alters state not tracked by the current version of
+ *     libvirt is possible as a means to test new qemu features before
+ *     they have support in libvirt, but no guarantees are made to safety
  *
  * If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is
  * considered to be a human monitor command and libvirt will automatically
  * convert it into QMP if needed.  In that case the @result will also
  * be converted back from QMP.
  *
- * If successful, @result will be filled as a string with the output
- * of the @cmd. And other APIs should operate normally (provided the
- * above requirements were honoured
+ * If successful, @result will be filled with the string output of the
+ * @cmd, and the caller must free this string.
  *
  * Returns 0 in case of success, -1 in case of failure
  *
@@ -124,11 +119,11 @@ error:
  * @pid: the UNIX process ID of the external QEMU process
  * @flags: optional flags, currently unused
  *
- * This API is QEMU specific, so will only work with hypervisor
+ * This API is QEMU specific, so it will only work with hypervisor
  * connections to the QEMU driver.
  *
  * This API will attach to an externally launched QEMU process
- * identified by @pid. There are several requirements to succcesfully
+ * identified by @pid. There are several requirements to successfully
  * attach to an external QEMU process:
  *
  *   - It must have been started with a monitor socket using the UNIX
@@ -140,7 +135,7 @@ error:
  *
  * If successful, then the guest will appear in the list of running
  * domains for this connection, and other APIs should operate
- * normally (provided the above requirements were honoured
+ * normally (provided the above requirements were honored).
  *
  * Returns a new domain object on success, NULL otherwise
  */