[libvirt] [PATCH] 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. --- src/libvirt-qemu.c | 31 +++++++++++++------------------ 1 files changed, 13 insertions(+), 18 deletions(-) diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c index b46868f..248cc33 100644 --- 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 */ -- 1.7.4.4