From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:39583) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYfq-0000Lk-Ne for qemu-devel@nongnu.org; Thu, 12 May 2011 12:23:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QKYfm-0001Co-FM for qemu-devel@nongnu.org; Thu, 12 May 2011 12:23:38 -0400 Received: from mail-gw0-f45.google.com ([74.125.83.45]:37014) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYfm-0001Cc-8b for qemu-devel@nongnu.org; Thu, 12 May 2011 12:23:34 -0400 Received: by gwb19 with SMTP id 19so688166gwb.4 for ; Thu, 12 May 2011 09:23:33 -0700 (PDT) Message-ID: <4DCC0981.4070801@codemonkey.ws> Date: Thu, 12 May 2011 11:23:29 -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> <4DCBFE2F.7040202@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:08 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 ... >> >> Inline documentation is bad. Our documentation should be >> centralized. That's the only way to keep it consistent and thorough. > > External documentation of code details is bad. Our documentation should > be next to the code. That's the only way to keep it up-to-date and > consistent with the code. qdev properties are *not* code details. It's a public user interface that we have to support for every. It should be disconnected from the internal implementation. And yes, the incestuous relationship that exists today is a problem, but it's one we're going to have to live with. > >> There's no way to easily extract the inline docs in a complete way >> since some devices are built conditionally. > > For each configured target: extract docs of the devices it builds > Concatenate and discard the duplicates > > Yes, that means you don't get docs for devices none of your targets has. > That's a feature. If you really want docs for all devices, build all > targets. But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? Regards, Anthony Liguori >