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

[Anthony Liguori <anthony@codemonkey.ws>]

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.

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.

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.

Regards,

Anthony Liguori

> Changes from previous send:
> - Removed the 'RFC' tag
> - Not using macros in net.h (Markus)
>
> It'll be helpful to have people submit some short descriptive text for
> the subsystems they care about.
>
> Amit Shah (5):
>    qdev: Add a description field for qdev properties for documentation
>    virtio-serial: Add description fields for qdev properties
>    net.h: Add description fields for qdev properites
>    qdev: Re-arrange code to have device properties shown from own
>      function
>    qdev: Add new '-device help' option, shows all devices and properties
>
>   block_int.h           |   10 +++---
>   hw/a9mpcore.c         |    2 +-
>   hw/acpi_piix4.c       |    2 +-
>   hw/arm11mpcore.c      |    4 +-
>   hw/arm_sysctl.c       |    4 +-
>   hw/armv7m.c           |    2 +-
>   hw/cs4231a.c          |    6 ++--
>   hw/debugcon.c         |    6 ++--
>   hw/eccmemctl.c        |    2 +-
>   hw/escc.c             |   16 +++++-----
>   hw/etraxfs_pic.c      |    3 +-
>   hw/fdc.c              |   10 +++---
>   hw/gus.c              |    8 ++--
>   hw/i2c.c              |    2 +-
>   hw/ide/cmd646.c       |    2 +-
>   hw/ide/isa.c          |    6 ++--
>   hw/ide/qdev.c         |    4 +-
>   hw/integratorcp.c     |    2 +-
>   hw/lance.c            |    2 +-
>   hw/m48t59.c           |   12 ++++----
>   hw/mc146818rtc.c      |    2 +-
>   hw/ne2000-isa.c       |    4 +-
>   hw/parallel.c         |    8 ++--
>   hw/pci.c              |   10 +++---
>   hw/qdev-addr.h        |    4 +-
>   hw/qdev.c             |   51 +++++++++++++++++++++------------
>   hw/qdev.h             |   75 ++++++++++++++++++++++++++-----------------------
>   hw/s390-virtio-bus.c  |    2 +-
>   hw/sb16.c             |   10 +++---
>   hw/scsi-bus.c         |    2 +-
>   hw/scsi-disk.c        |    2 +-
>   hw/serial.c           |    8 ++--
>   hw/slavio_timer.c     |    2 +-
>   hw/smbus_eeprom.c     |    2 +-
>   hw/sparc32_dma.c      |    2 +-
>   hw/sun4m.c            |    2 +-
>   hw/sun4m_iommu.c      |    2 +-
>   hw/sun4u.c            |    2 +-
>   hw/syborg_fb.c        |    4 +-
>   hw/syborg_interrupt.c |    2 +-
>   hw/syborg_keyboard.c  |    2 +-
>   hw/syborg_pointer.c   |    4 +-
>   hw/syborg_serial.c    |    2 +-
>   hw/syborg_timer.c     |    2 +-
>   hw/tcx.c              |   10 +++---
>   hw/usb-ohci.c         |    4 +-
>   hw/usb-serial.c       |   12 ++++----
>   hw/vga-pci.c          |    4 +-
>   hw/virtio-blk.h       |    4 +-
>   hw/virtio-console.c   |   19 ++++++++----
>   hw/virtio-net.h       |   51 +++++++++++++++++++++------------
>   hw/virtio-pci.c       |   16 +++++-----
>   hw/virtio-serial.h    |   13 ++++++++
>   hw/virtio.h           |    2 +-
>   hw/xilinx_ethlite.c   |    6 ++-
>   hw/xilinx_intc.c      |    3 +-
>   hw/xilinx_timer.c     |    4 +-
>   net.h                 |    9 ++++--
>   usb-linux.c           |    8 ++--
>   59 files changed, 268 insertions(+), 208 deletions(-)
>
>
>