From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=44886 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OOCwj-0000Gj-VJ for qemu-devel@nongnu.org; Mon, 14 Jun 2010 12:55:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OOCwi-0007K0-8W for qemu-devel@nongnu.org; Mon, 14 Jun 2010 12:55:37 -0400 Received: from mail-qy0-f173.google.com ([209.85.216.173]:62196) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OOCwi-0007Jl-63 for qemu-devel@nongnu.org; Mon, 14 Jun 2010 12:55:36 -0400 Received: by qyk5 with SMTP id 5so469468qyk.4 for ; Mon, 14 Jun 2010 09:55:35 -0700 (PDT) Message-ID: <4C165F05.6060700@codemonkey.ws> Date: Mon, 14 Jun 2010 11:55:33 -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: <4C0D19BC.6030305@codemonkey.ws> <20100608052104.GC11937@amit-laptop.redhat.com> In-Reply-To: <20100608052104.GC11937@amit-laptop.redhat.com> 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: qemu list , Juan Quintela , Markus Armbruster , Gerd Hoffmann 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 > > >