Anthony Liguori <aligu...@linux.vnet.ibm.com> writes: > On 02/24/2011 10:20 AM, Markus Armbruster wrote: >> Anthony Liguori<aligu...@linux.vnet.ibm.com> writes: >> >> >>> On 02/24/2011 02:33 AM, Markus Armbruster wrote: >>> >>>> Anthony Liguori<anth...@codemonkey.ws> writes: [...] >>>>> Please describe all expected errors. >>>>> >>>>> >>>> Quoting qmp-commands.hx: >>>> >>>> 3. Errors, in special, are not documented. Applications should NOT >>>> check >>>> for specific errors classes or data (it's strongly recommended to >>>> only >>>> check for the "error" key) >>>> >>>> Indeed, not a single error is documented there. This is intentional. >>>> >>>> >>> Yeah, but we're not 0.14 anymore and for 0.15, we need to document >>> errors. If you are suggesting I send a patch to remove that section, >>> I'm more than happy to. >>> >> Two separate issues here: 1. Are we ready to commit to the current >> design of errors, and 2. Is it fair to reject Lai's patch now because he >> doesn't document his errors. >> >> I'm not commenting on 1. here. >> >> Regarding 2.: rejecting a patch because it doesn't document an aspect >> that current master intentionally leaves undocumented is not how you >> treat contributors. At least not if you want any other than certified >> masochists who enjoy pain, and professionals who get adequately >> compensated for it. >> >> Lead by example, not by fiat. >> > > http://repo.or.cz/w/qemu/aliguori.git/blob/refs/heads/glib:/qmp-schema.json > > I am in the process of documenting the errors of every command. It's > a royal pain but I'm going to document everything we have right now. > It's actually the last bit of work I need to finish before sending > QAPI out. > > So for new commands being added, it would be hugely helpful for the > authors to document the errors such that I don't have to reverse > engineer all of the possible error conditions.
The moment this lands in master, you can begin to demand error descriptions from contributors. Until then, I'll NAK error descriptions in qmp-commands.txt. We left them undocumented there for good reasons: >>>> Once we have an error design in place that has a reasonable hope to >>>> stand the test of time, and have errors documented for at least some of >>>> the commands here, we can start to require proper error documentation >>>> for new commands. But not now. I won't NAK non-normative error descriptions, say in commit messages, or in comments. And I won't object to you asking for them. But I feel you really shouldn't make it a condition for committing patches. Especially not for simple patches that have been on list for months.
