Michael Roth <mdr...@linux.vnet.ibm.com> writes: > Quoting Markus Armbruster (2015-09-03 12:01:20) >> Michael Roth <mdr...@linux.vnet.ibm.com> writes: >> >> > Quoting Eric Blake (2015-09-03 09:31:01) >> >> On 09/03/2015 03:26 AM, Markus Armbruster wrote: >> >> >> >> >> >> I think we need to be careful that these descriptions are not >> >> >> interpreted by clients as an alternative to the more-specific >> >> >> constraints in the QAPI schema though. 'query-schema' seems >> >> >> a bit misleading in that regard, it appears to be more like >> >> >> 'query-schema-encoding' in function. But not sure it's worth >> >> >> renaming or anything so long as the documentation is clear. >> >> > >> >> > You have a point: "schema" can mean two related, yet different things. >> >> > There's the QAPI schema, and there's the QMP (the wire protocol) schema. >> >> > QMP introspection is about the latter, not the former. >> >> > >> >> > If we want to avoid the ambiguity, we could call the command >> >> > query-qmp-schema or something. >> >> > >> >> > Renaming query-schema now might confuse people coming from my KVM Forum >> >> > talk slightly, but if we can agree on a better name, let's do it. >> >> >> >> I'm okay if you want to use 'query-qmp-schema'; it's a bit longer, but >> >> more precise, and doesn't cause too much grief to change the name at >> >> this point in the game. >> > >> > I'm also okay with this. It avoids confusion down that road if we >> > ever introduced, say, a query-ber-schema or something. >> > >> > I have some minor reservations: I think query-qmp-schema-mapping or >> > query-qmp-schema-encoding, i.e. "give me information on how the >> > [QAPI] schema maps to the QMP wire protocol", is more correct. >> > query-qmp-schema reads like "give me the complete schema for the >> > QMP wire protocol", which makes it more tempting to treat the >> > result as a complete schema, rather than a component of what's >> > defined by the QAPI schema. >> >> Well, it *is* the schema for the QMP wire protocol. Which happens to be >> mechanically derived from the QAPI schema. > > True, but the separation from QMP wire schema and QAPI interface schema > wouldn't be clear to most users. It would be fairly tempting/reasonable > for the author of a QMP client to assume the "QMP schema" was the > definitive source for how a client should interact with QEMU without > realizing or finding the need to reference the QAPI schema for more > specific constraints (like integer ranges).
The constraints not expressed in the QMP schema generally aren't expressed in the QAPI schema either, only its comments. Nevertheless, I quite agree our documentation should refer readers to the QAPI schema, because it's the source code, and as such it's written for humans. The value of query-qmp-schema is just for machines. > I'm somewhat harping on this because that's exactly the misconception > I had when I first looked at this series, which is why the loss of > information like integer ranges didn't seem acceptable to me initially. > > But I don't really have a problem with query-qmp-schema, the naming > comments are more a suggestion of the sort of confusion we should > try to clear up in the accompanying documentation. > >> >> > But in all likelihood trying to cram all that information into the >> > command name would probably just be confusing to most, so a simpler >> > name with clear documentation seems reasonable. >> >> I think query-qmp-schema hits the sweet spot between "ambiguous because >> it's too short" and "too long because we tried to make it unambiguous". >> I'll adopt it in v5. >> >> Regarding clear documentation: we don't have to get it perfect in the >> initial commit, but I'm of course happy to address review of RFC PATCH >> v4 in v5. >> > > Thanks, sounds reasonable to me. Okay, we got a plan. Thanks!