Anthony Liguori <anth...@codemonkey.ws> 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. [...]
