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

[Anthony Liguori <anthony@codemonkey.ws>]

On 02/18/2011 02:53 AM, Markus Armbruster wrote:
> 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.
>    

The blocker for me is the introduction of empty strings.   Doc 
extraction is a nice-to-have but I'd be inclined to merge w/o it.

Regards,

Anthony Liguori