Re: [Qemu-devel] [patch 1/3] mc146818rtc: add rtc_reset_reinjection QMP command

[Eric Blake]

On 06/02/2014 02:20 PM, Marcelo Tosatti wrote:
> On Mon, Jun 02, 2014 at 01:31:29PM -0600, Eric Blake wrote:
>> On 06/02/2014 11:51 AM, address@hidden wrote:
>>> It is necessary to reset RTC interrupt reinjection backlog if
>>> guest time is synchronized via a different mechanism, such as 
>>> QGA's guest-set-time command.
>>>

>>> +
>>> +##
>>> +# @: rtc-reset-reinjection
>>
>> s/: // to resemble most other commands
> 
> Several commands have ":". What is the correct syntax and why?

Alas, we don't have any automated program that strips these stylized
comments and turns them into formal documentation.  But the goal is that
some day we might, at which point, being consistent in our style is the
most likely to be successful.  The prevalent style appears to be:

##
# @command:
#
# Short summary
#
# @foo: describe mandatory option foo
#
# @bar: #optional describe optional option bar, and its default value
#       if omitted
#
# Returns: what to expect from the command
#
# Since: version it was introduced
##
{ 'command' ... }

Although I will admit that '@command' vs. '@command:' didn't have a
clear winner.  Maybe someone with OCD wants to do a pure cleanup patch
to get the file into a consistent state?  Until then, I'm pointing out
where things are definitely different (your '@: command' was an outlier)

>>>  EQMP
>>> +
>>> +#if defined (TARGET_I386)
>>> +    {
>>> +        .name       = "rtc_reset_reinjection",
>>
>> s/rtc_reset_reinjection/rtc-reset-reinjection/
> 
> This is a function name.

No, it is a QMP command name.  See "send-key" for an example.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature