[Qemu-devel] RFC: Syncing documentation vs. -help vs. qemu_options table

[Blue Swirl]

Hi,

It would be nice if the documentation about command line switches,
-help text and qemu_options table would be kept more easily in sync.

In true Qemu tradition, I propose as a solution to make an include
file that is parsed once for getting the enums, another time for
getopt tables and third time for help message (or these last two may
be combined in a more advanced structure). The documentation could be
generated from the same file with CPP. The advantage is that all stuff
would be in a single location, so developers are less likely to forget
to update docs when adding new switches.

Considering -parallel switch as an example, the file would contain
something like:
DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, "-parallel dev
redirect the parallel port to char device 'dev'\n")
#ifdef DOC
@item -parallel @var{dev}
Redirect the virtual parallel port to host device @var{dev} (same
devices as the serial port). On Linux hosts, @file{/dev/parportN} can
be used to use hardware devices connected on the corresponding host
parallel port.

This option can be used several times to simulate up to 3 parallel
ports.

Use @code{-parallel none} to disable all parallel ports.
#endif /* DOC */

Parsing this in enum mode would yield
 QEMU_OPTION_parallel,

In getopt generation mode:
{ "parallel", HAS_ARG, QEMU_OPTION_parallel },

And the generated qemu-doc.texi part would contain the texi version.

The needed macro magic left as an exercise for the reader.

TARGET_I386-only stuff etc. (especially considering the texi) may need
more complex #ifdefs.

It would also be possible to include the full documentation for each
switch into Qemu, so there could be more detailed builtin help for
each command line switch (like svn help vs. svn help commit).

Comments?