qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-devel] [PATCH 0/5] Add '-device help' output for device params


From: Markus Armbruster
Subject: Re: [Qemu-devel] [PATCH 0/5] Add '-device help' output for device params and help text
Date: Tue, 15 Jun 2010 11:17:40 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1 (gnu/linux)

Anthony Liguori <address@hidden> writes:

> On 06/08/2010 12:21 AM, Amit Shah wrote:
>> On (Mon) Jun 07 2010 [11:09:32], Anthony Liguori wrote:
>>    
>>> On 05/31/2010 07:41 AM, Amit Shah wrote:
>>>      
>>>> Hello,
>>>>
>>>> This patch series adds support to specify some descriptive help text
>>>> to qdev device parameters. This series adds some help text to the
>>>> virtserialport and net family of devices as an example, and the new
>>>> output is shown in the respective commits.
>>>>
>>>> This series also adds a new '-device help' option that lists all the
>>>> available qdev devices (which is avl. via -device ? now), and adds
>>>> each device's parameters to the output listing. This output also shows
>>>> the descriptive text.
>>>>
>>>> The idea is to auto-generate documentation from code and to populate
>>>> some wiki / qemu-doc.texi using this new target.
>>>>        
>>> I really dislike having options print their own help.
>>>      
>> Why? I really like it, coders can embed help exactly in the same place
>> they're adding / changing options and there's much less chance of
>> someone missing updating help strings when updating / adding options.
>>    
>
> Because it's inconsistent from a UI perspective.  -device help, -M ?, etc.
>
> How's a user supposed to know which options can display help and what
> the magic invocation is that is used to display it?
>
> -help device/-help machine
>
> Provides a consistent, self discoverable interface for users to get
> detailed inline help.

Additional advantages:

* No special case for '?' in option processing.  No risk '?' for help
  collides with a legitimate non-help option argument starting with '?'.

* No more "-device x: Parameter 'driver' expects a driver name" just
  because you happen to have a file named "x" around, and you forgot to
  quote.

>>> Maybe we can introduce a proper -help option that takes an argument
>>> that can display subsystem specific help?
>>>
>>> For instance:
>>>
>>> qemu -help device
>>>
>>> Would display the help output in this series.
>>>      
>> What I'm adding here is similar; instead of -help device, I'm adding
>> -device help, and I think it's nicer because it fits directly in the
>> qdev code.
>>    
>
> The UI should not be a consequence of the implementation.

Yes.  And "-help FOO" can certainly be engineered so that FOO's
documentation is still next to FOO's implementation.

[...]



reply via email to

[Prev in Thread] Current Thread [Next in Thread]