Re: [Qemu-devel] [PATCH REBASE/RESEND 0/4] Auto-document qdev devices

[Markus Armbruster <armbru@redhat.com>]

Anthony Liguori <anthony@codemonkey.ws> writes:

> On 02/04/2011 12:18 AM, Amit Shah wrote:
>> Hello,
>>
>> This is yet another rebase of the patchset I'd sent earlier.
>>
>> The usual notes apply: this is just the start, just getting the
>> framework in place and a few examples so that people can then pick up
>> and start documenting their devices and options.  We want to see all
>> of the devices covered, and hopefully turn on build_bug_on() on an
>> empty doc string.
>>
>> Maintainers should perhaps also look for patches that introduce
>> options without documentation.
>>
>> That's the long-term goal (0.15-final).  For short-term, I'll be
>> preparing follow-on patches that add doc strings for a few more
>> options and perhaps bug people based on git history as to what
>> documentation is to be added for some options.  Also to incorporate
>> Markus's comments on beautifying output.
>>
>> The earlier this patchset goes in the better since it'll reduce
>> conflicts and rebases needed.
>>
>> If this looks acceptable, please apply!
>>    
>
> I think we need to approach this in such a way that we generate not
> only inline documentation but out of line documentation.
>
> We need a way to extract the docs into a file.  That could mean having
> something like a .hx file or just doing some clever things with grep
> DEFINE_PROP.

Or stupid things with linking docs into a simple program that prints
them.

Anyway, let's not overengineer now.  This patch is a step forward: the
user gets help where there was none before.  It doesn't prejudice
further steps forward, such as putting the help information to
additional uses.