Re: [Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5)

["Marc-André Lureau" <mlureau@redhat.com>]

Hi

----- Original Message -----
> Marc-André Lureau <marcandre.lureau@redhat.com> writes:
> 
> > Hi,
> >
> > The QAPI documentation is currently done in two places, the json
> > schema and a more human-friendly text file. The goal is to avoid
> > duplication and to generate friendly versions from the schema (pdf,
> > man etc).  Thus, all documentation should be moved to the schema.
> >
> > In order to facilitate the review, the documentation move has been
> > splitted, and is going to sent by chunks of ~30 patches. This way it
> > should take about 5 series to complete (~150 patches). I suggest that
> > the qapi maintainers (Markus/Eric) compile the reviewed patches in a
> > branch and merge upstream in one go (either merging move commits or
> > not) when the series complete and the documentation is finally
> > generated to avoid an in-between state.
> >
> > The wip branch with all the pending patches:
> > https://github.com/elmarco/qemu/commits/qapi-doc
> 
> Ah, now I understand why you asked whether to post everything!  The
> "move FOO doc to schema" patches make no sense until the very end of the
> full branch, when you actually generate documentation from the schema.
> 
> Perhaps you could structure like this:
> 
> 1. Fix existing issues in QAPI schema comments
> 
> 2. Generate documentation from it (not a replacement for
>    qmp-commands.txt, yet)
> 
> 3. Merge qmp-commands.txt into QAPI schema comments, step by step
> 
>    (a) If you only update the QAPI schema comments, qmp-commands.txt
>    stays intact throughout this work.
> 
>    (b) If you delete qmp-commands.txt section as you cover them in the
>    QAPI schema, command documentation regresses temporarily.  Tolerable,
>    but needs to be explained in commit messages.  Your choice.
> 
> 4. Generated documentation now contains everything qmp-commands.txt
>    contains; delete qmp-commands.txt
> 
> Getting to this structure with option (3b) could be as simple as
> reordering your branch.

3(a) makes it hard to check that everything has been moved properly, while removing 3(b) makes it clear what is removed and adjusted in the corresponding schema doc, and by the end of 3(b) it's clear that nothing has been left behind.

Generating the documentation before the end of 3(b) will also lead to temporarily incomplete generated doc, and will conflict with existing qmp-commands.txt.

That's why I think the best solution is to go through 3(b) now, collect the move in a branch and push it in one go when qmp-commands.txt is empty and the doc is generated.