From: Markus Armbruster <armbru@redhat.com>
Subject: Re: [Qemu-devel] [PATCH REBASE/RESEND 0/4] Auto-document qdev devices
References: <cover.1296800129.git.amit.shah@redhat.com>
	<4D5AA5E7.40203@codemonkey.ws>
Date: Fri, 18 Feb 2011 09:53:02 +0100
In-Reply-To: <4D5AA5E7.40203@codemonkey.ws> (Anthony Liguori's message of
	"Tue, 15 Feb 2011 10:12:23 -0600")
Message-ID: <m3d3mp4tch.fsf@blackfin.pond.sub.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
To: Anthony Liguori <anthony@codemonkey.ws>
Cc: Amit Shah <amit.shah@redhat.com>, qemu list <qemu-devel@nongnu.org>

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.