On Wed, 25 Jun 2014 14:13:37 -0600 Eric Blake <ebl...@redhat.com> wrote:
> On 06/25/2014 01:50 PM, Luiz Capitulino wrote: > > >> Then again, qmp-commands.txt is generated from qmp-commands.hx, which > >> duplicates information already in qapi-schema.json (and friends, now). > >> Would it be better to just install the .json files? Is it time to > >> finally bite the bullet and figure out how to get rid of duplication by > >> dropping qmp-commands.hx, and instead listing example usage directly in > >> the qapi-schema.json file? I'm not sure if we have a good plan in place > >> for user-facing documentation, even if the move to events-as-QAPI was > >> desirable. > > > > My original plan was to generate qmp-commands.txt & qmp-evets.txt from > > the schema file(s). I'm not sure if the .json files are consumable to > > non-qemu/libvirt developers. If you think they are then I'd be fine with > > installing them. > > The .json files are what _I_ refer to (but I'm probably biased, since > I've become a vested partner in the json files in the meantime); for > someone encountering the docs with no prior experience, I'm not sure how > much value-added the qmp-commands.txt was providing. > > > > > Wrt the examples, my only concern about having them in the schema is > > that the examples are in QMP format but in the past we were also planning > > on having C support via libqmp. If what we have today is what matters, > > then we can just move the examples to the schema files. > > Putting the examples in the .json files also comes with its own > interesting issues - do you prefix every line with # comment markers (so > the examples are no longer copy-paste, but now copy-paste-modify)? Or do > we do it as top-level JSON elements, perhaps via a new item that the > generators ignore but which a doc conversion tool could consume? Maybe: > { 'example': { > 'client': > {"command": {"foo", "arguments": { "hello": "world" } } }, > 'server': > {"reply": {} } > } } > > Michal's hack at least ensures that we have event documentation, even if > the format changed compared to the 2.0 docs, and even if we don't have > time to get something better in place before 2.1 goes out. So all of > this conversation on ways to do better is nice, but if we don't get > there quickly, I could at least live with Michal's patch in the short term. I honestly don't know what's the best thing to do here. I can live with this patch too, although having some introductory comments at the top of the file saying what it is would be nicer.