[libvirt] [PATCH 3/7] qemu_api: Add comments for API virDomainQemuMonitorCommand

[Eric Blake]

On 09/09/2011 05:24 AM, Osier Yang wrote:
> + *
> + * Send an arbitrary monitor command @cmd to @domain through the
> + * qemu monitor. There are several requirements to safely and
> + * succcesfully to use this API:

You've already pushed, but with a number of doc problems.

s/succcesfully/successfully/ (copy-and-paste issue)

> + *
> + *   - 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.

s/libvirtd crashed/libvirtd to crash/

> + *   - If the @cmd is intend to change domain configuration, it must

s/intend/intended/

> + *     be no or other configuration changes can have been made via

s/it must be no or other/there must have been no other/

s/can have been made/made/

> + *     the monitor since it started.
> + *   - The '-name' and '-uuid' arguments should have been set (not
> + *     mandatory, but strongly recommended)

Is this really appropriate comments for virDomainQemuMonitorCommand?  It 
sounds like you are repeating the help for virDomainQemuAttach.


> + *
> + * 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

Prefer US spelling in public docs: s/honoured/honored/

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org