[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Qemu-devel] Re: [PATCH 1/2] QMP: Introduce commands doc

From: Jan Kiszka
Subject: [Qemu-devel] Re: [PATCH 1/2] QMP: Introduce commands doc
Date: Sat, 15 May 2010 10:42:44 +0200
User-agent: Mozilla/5.0 (X11; U; Linux i686 (x86_64); de; rv: Gecko/20080226 SUSE/ Thunderbird/ Mnenhy/

Luiz Capitulino wrote:
> On Fri, 14 May 2010 19:08:07 +0200
> Jan Kiszka <address@hidden> wrote:
>> Avi Kivity wrote:
>>> On 05/14/2010 08:01 PM, Avi Kivity wrote:
>>>> On 05/14/2010 07:52 PM, Jan Kiszka wrote:
>>>>>> In order not to compromise QMP adoption and make users' life easier,
>>>>>> this commit adds a simple text documentation which fully describes
>>>>>> all QMP supported commands.
>>>>>> This is not ideal for a number of reasons (harder to maintain,
>>>>>> text-only, etc) but does improve the current situation.
>>>>> Even if it's temporary - maintaining it in a separate file looks rather
>>>>> unhandy.
>>>>> Can't we generate the per-command documentation snippets also from
>>>>> qemu-monitor.hx and merge them with a header/footer into some text file?
>>>>> That .hx file is the one anyone adding/converting commands has to touch
>>>>> anyway.
>>>> If we do, then the generated documentation should be included in the 
>>>> patch changelog for review.
>>> I mean, a patch introducing or modifying a monitor command.
>> The snippets should be readable by themselves. I'm only proposing to
>> keep them in the central file, at the same location where the others
>> are. There is no difference compared to existing monitor commands, we
>> just add the third documentation snippet, this time for QMP.
>  It's not only the snippets. We add a json type for each parameter, a
> more descriptive info and notes. Only QMP commands should be shown
> this way.

Whatever its semantic is, technically it's a text block of a few lines
that has to be added somewhere.

>  I'm sure there's a way to hack the qemu's doc script to do all this,
> but the right solution is to move _everything_ to json and generate good,
> well formatted documentation from there (along with self-description).

I'm not talking about The Right solution, I'm talking about a more handy
temporary setup. When do you plan to refactor the command documentation
that way? And how many commands will be touched in the meantime?

>  Also, adapting things will take time and this will delay even more this
> doc to be merged, which is what I'm trying to avoid.

I can provide you the patch for hxtool and Makefile (a few lines), and
I'm willing to split up the existing doc, just drop me a note. So
nothing needs to be delayed any further.


Attachment: signature.asc
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]