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

[Anthony Liguori <anthony@codemonkey.ws>]

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.

>> 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.

>> My other concern is that we now have a big mess of properties that
>> don't have help text.  What are the chances that anyone is going to
>> go through and do this?
>>
>> I'd rather we bite the bullet and add help everywhere before merging
>> any of this because experience has shown that existing code usually
>> never gets converted if not converted all at once.
>>      
> Let me put my community contributor hat on: we're not really giving away
> vibes that qemu has to be 100% enterprise-ready at each commit, are we?
> qemu is a *development* project, and development happens one small
> commit at a time, commit early and often. If I'm going to have to
> maintiain hundreds of small help-related patches, it's soon going to
> grow stale as people change related code and in the end I'll grow
> frustrated and drop then entire exercise. Not the first time that
> would've happened.
>    

The problem with this argument is that people introduce things like this 
with this exact argument and then nothing every ends up getting help 
options.

> On the other hand, we commit this right away, and interested developers
> in their own domains start contributing the small one-liners which
> brings their subsystem up to the mark for documentation.
>    

It simply doesn't happen or else it already would have.  The best way to 
make this is a one time painful conversion followed by strong 
enforcement that all new options take help strings.

Regards,

Anthony Liguori

> I think this is the best way to contribute such patches.
>
> If you think some devices are going to go documentation-less, instead of
> empty strings, I can do "description needed" strings, which can even
> invite first-time contributors grep through this and contribute the
> one-liners.
>
> If the enterprise people want this fixed before any enterprise release,
> they better commit resources to ensure they don't release anything that
> has a 'documentation needed!' line. :-)
>
> 		Amit
>
>
>