Received: from [140.186.70.92] (port=54098 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OOSM5-0002Mg-8S for qemu-devel@nongnu.org; Tue, 15 Jun 2010 05:22:51 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OOSM4-0004KA-1K for qemu-devel@nongnu.org; Tue, 15 Jun 2010 05:22:49 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37444) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OOSM3-0004Jy-MO for qemu-devel@nongnu.org; Tue, 15 Jun 2010 05:22:48 -0400 From: Markus Armbruster 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> <4C165F05.6060700@codemonkey.ws> Date: Tue, 15 Jun 2010 11:17:40 +0200 In-Reply-To: <4C165F05.6060700@codemonkey.ws> (Anthony Liguori's message of "Mon, 14 Jun 2010 11:55:33 -0500") Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Anthony Liguori Cc: Amit Shah , Gerd Hoffmann , qemu list , Juan Quintela Anthony Liguori writes: > 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. Additional advantages: * No special case for '?' in option processing. No risk '?' for help collides with a legitimate non-help option argument starting with '?'. * No more "-device x: Parameter 'driver' expects a driver name" just because you happen to have a file named "x" around, and you forgot to quote. >>> 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. Yes. And "-help FOO" can certainly be engineered so that FOO's documentation is still next to FOO's implementation. [...]