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

[Anthony Liguori]

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