From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:39913) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYiF-0001K9-Bn for qemu-devel@nongnu.org; Thu, 12 May 2011 12:26:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QKYiB-0001bS-BX for qemu-devel@nongnu.org; Thu, 12 May 2011 12:26:07 -0400 Received: from mail-gx0-f173.google.com ([209.85.161.173]:58176) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYiB-0001bB-7q for qemu-devel@nongnu.org; Thu, 12 May 2011 12:26:03 -0400 Received: by gxk26 with SMTP id 26so691806gxk.4 for ; Thu, 12 May 2011 09:26:02 -0700 (PDT) Message-ID: <4DCC0A16.5090605@codemonkey.ws> Date: Thu, 12 May 2011 11:25:58 -0500 From: Anthony Liguori MIME-Version: 1.0 References: <1305023443-8722-1-git-send-email-kraxel@redhat.com> <201105101624.08253.bradh@frogmouth.net> <4DCBA79B.5040608@redhat.com> <4DCBFBFF.7000203@redhat.com> <4DCC039B.5070608@codemonkey.ws> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Markus Armbruster Cc: amit.shah@redhat.com, Gerd Hoffmann , Brad Hards , qemu-devel@nongnu.org On 05/12/2011 11:18 AM, Markus Armbruster wrote: > Anthony Liguori writes: > >> On 05/12/2011 10:25 AM, Gerd Hoffmann wrote: >>> Hi, >>> >>>>> What is the status of the qdev documentation patches btw.? >>>> >>>> http://lists.gnu.org/archive/html/qemu-devel/2011-02/msg02169.html >>> >>> What is the problem with the empty strings btw? >>> >>> The only way around I can see is having _DOC and _NODOC versions for all >>> the property macros, but I'd prefer to not have _NODOC macros in the >>> tree ... >> >> Here's an example of what I'm suggesting. I think we should just go >> with this and add better output as we go. >> >> But we need all of the qdev information.. not just a doc string for >> each property. > > Missing: make "device_add ?" show your device doc strings, and > "device_add NAME,?" show your property doc strings. I really dislike overloading things for inline help. Introducing a device_help is fine and hopefully you realize that generating this is trivial. > > Missing: automated check qdev-doc.json matches the code. Keeping the > docs far from the code is a bad idea even with such a check. I view this as a feature. What's documented is what's supported. Anything that isn't documented isn't supported. But yes, hopefully it's obvious that we can add automated checks to improve this. But if we're going to start somewhere, this is where I think we should start. Regards, Anthony Liguori > [...] >