"Michael S. Tsirkin" <m...@redhat.com> writes: > On Tue, Sep 16, 2014 at 10:01:19PM +0300, Michael S. Tsirkin wrote: >> On Tue, Sep 16, 2014 at 08:31:08PM +0200, Paolo Bonzini wrote: >> > Il 16/09/2014 18:56, Michael S. Tsirkin ha scritto: >> > > On Tue, Sep 16, 2014 at 06:27:51PM +0200, Paolo Bonzini wrote: >> > >> Il 16/09/2014 18:26, Michael S. Tsirkin ha scritto: >> > >>> Right so types should be explicit. >> > >>> If an arbitrary string isn't allowed, this should be documented. >> > >>> It's not great as is: what's the format for macaddr? AA:BB:CC:DD:EE:FF? >> > >>> aa:bb:cc:dd:ee:ff? aabbccddeeff? 0xaabbccddeeff? >> > >>> But just saying "string" is going in the wrong direction imho. >> > >> >> > >> That's the purpose of documentation (docs/qdev-device-use.txt), >> > > >> > > That's not user documentation, that's developer documentation, >> > > isn't it? >> > >> > It's user documentation. It's not distributed because we suck at >> > documentation. >> > >> > >> and even >> > >> then is better done with examples. I don't think doing it in -device >> > >> foo,help (which I'm not even sure is particularly helpful. >> > > >> > > -device foo,help isn't helpful at all because it does not >> > > tell people what does each option do. >> > > But it really should be fixed. >> > >> > Exactly. >> > >> > >> I'm sympathetic towards fixing the drive->str change, but I have no idea >> > >> how to do it. >> > > >> > > Change legacy_name to point to a detailed human-readable >> > > description of the type? >> > > E.g. "Ethernet 6-byte MAC Address, format: AA:BB:CC:DD:EE:FF"? >> > >> > If libvirt can cope with >> > >> > e1000.mac=str (Ethernet 6-byte MAC Address, format: AA:BB:CC:DD:EE:FF) >> > >> > that would work for me. >> >> Shouldn't "str" be "string" in HMP?
Probably. What about QMP? JSON calls the type "string". Possible justification for "str": QMP makes up its own type system, losely based on JSON's, with its own terminology. I'm not sure "=T" adds value over the description. Certainly not in the example above. >> Eblake - type is ignored right? Does this mean anything to the right of >> = is ignored? As far as I can tell from the libvirt sources: yes. >> > > We really really should add description to all properties, too. >> > >> > This is a huge job. We have hundreds of properties. >> > >> > Paolo >> >> Right. If we don't start we won't get there though, will we? >> > > And, we'll keep adding undocumented ones. Agree with all three points. We should get our act together on property documentation.
