From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=57880 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OLetU-0001C5-2z for qemu-devel@nongnu.org; Mon, 07 Jun 2010 12:09:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OLetO-0004fS-VQ for qemu-devel@nongnu.org; Mon, 07 Jun 2010 12:09:43 -0400 Received: from mail-iw0-f173.google.com ([209.85.214.173]:33813) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OLetO-0004fN-Qj for qemu-devel@nongnu.org; Mon, 07 Jun 2010 12:09:38 -0400 Received: by iwn41 with SMTP id 41so3660526iwn.4 for ; Mon, 07 Jun 2010 09:09:38 -0700 (PDT) Message-ID: <4C0D19BC.6030305@codemonkey.ws> Date: Mon, 07 Jun 2010 11:09:32 -0500 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH 0/5] Add '-device help' output for device params and help text References: In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Amit Shah Cc: Markus Armbruster , Gerd Hoffmann , qemu list , Juan Quintela 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(-) > > >