From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=60970 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Pq4B2-0005JN-KZ for qemu-devel@nongnu.org; Thu, 17 Feb 2011 08:45:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Pq4B1-0005B1-3R for qemu-devel@nongnu.org; Thu, 17 Feb 2011 08:45:48 -0500 Received: from mx1.redhat.com ([209.132.183.28]:32825) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Pq4B0-0005Ag-PD for qemu-devel@nongnu.org; Thu, 17 Feb 2011 08:45:47 -0500 Date: Thu, 17 Feb 2011 19:15:39 +0530 From: Amit Shah Subject: Re: [Qemu-devel] [PATCH REBASE/RESEND 0/4] Auto-document qdev devices Message-ID: <20110217130944.GE27487@amit-x200.redhat.com> References: <4D5AA5E7.40203@codemonkey.ws> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4D5AA5E7.40203@codemonkey.ws> List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Anthony Liguori Cc: qemu list , Markus Armbruster On (Tue) 15 Feb 2011 [10:12:23], Anthony Liguori wrote: > 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. An external tool that uses grep, sed and awk will work just fine to export all of this to some wiki page or anywhere else desirable. Amit