Re: [Qemu-devel] [PATCH 0/3] Fix confused output for alias properties

[Paolo Bonzini]

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.

> We really really should add description to all properties, too.

This is a huge job.  We have hundreds of properties.

Paolo