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

[Markus Armbruster]

Jan Kiszka <address@hidden> writes:

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

The current documentation is just a block of text, yes.  Fine for human
consumption.  Useless for QMP self-documentation, i.e. machine-readable
documentation exposed over QMP.  There, we need a bit more structure.

qemu-monitor.gx is a sub-optimal permanent place for command
documentation.  The command documentation source should live right next
to the command code, because that increases its chances to get updated
along with the code.

Naturally, we also need a way to generate something like
qmp-commands.txt from it, for easier review, and for the human users of
QMP.

>>  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?

We need self-documentation badly right after we declare QMP stable,
i.e. 0.13.  Because any change after that needs to be discoverable by
QMP clients.

Ideally, we put it in before 0.13.  If we can't pull that off, then
early in the 0.14 cycle.  Help appreciated!

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

Moving it from one temporary, sub-optimal place (QMP/qmp-commands.txt)
to another temporary, sub-optimal place (qemu-monitor.hx) doesn't seem
like a win to me.  Should temporary macro wizardry be required for that
(hxtool patch), the deal gets even less appealing.

>                                                                So
> nothing needs to be delayed any further.

Well, it's being delayed :)

Let's commit the sucker as is.  We can still move it into
qemu-monitor.hx afterwards.  Commits are cheap, waiting for the perfect
patch isn't.