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

[Amit Shah]

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.

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

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

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.

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