[Top][All Lists]
[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.
[...]