From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=58221 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PqS6K-0001CK-4y for qemu-devel@nongnu.org; Fri, 18 Feb 2011 10:18:34 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PqS6I-0003gt-Md for qemu-devel@nongnu.org; Fri, 18 Feb 2011 10:18:31 -0500 Received: from mail-qw0-f45.google.com ([209.85.216.45]:55990) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PqS6I-0003fy-IR for qemu-devel@nongnu.org; Fri, 18 Feb 2011 10:18:30 -0500 Received: by qwk4 with SMTP id 4so3501142qwk.4 for ; Fri, 18 Feb 2011 07:18:29 -0800 (PST) Message-ID: <4D5E8DC3.4090502@codemonkey.ws> Date: Fri, 18 Feb 2011 09:18:27 -0600 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH REBASE/RESEND 0/4] Auto-document qdev devices References: <4D5AA5E7.40203@codemonkey.ws> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Markus Armbruster Cc: Amit Shah , qemu list On 02/18/2011 02:53 AM, Markus Armbruster wrote: > Anthony Liguori 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