From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:48877) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKaIG-0001bN-Du for qemu-devel@nongnu.org; Thu, 12 May 2011 14:07:31 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QKaIA-0002oF-Ug for qemu-devel@nongnu.org; Thu, 12 May 2011 14:07:24 -0400 Received: from mail-gw0-f45.google.com ([74.125.83.45]:64719) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKaIA-0002nV-DN for qemu-devel@nongnu.org; Thu, 12 May 2011 14:07:18 -0400 Received: by gwb19 with SMTP id 19so738988gwb.4 for ; Thu, 12 May 2011 11:07:17 -0700 (PDT) Message-ID: <4DCC21D2.7000409@codemonkey.ws> Date: Thu, 12 May 2011 13:07:14 -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> <4DCC0981.4070801@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 12:58 PM, Markus Armbruster wrote: > Anthony Liguori writes: > >> 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. > > The fact that they are public user interface doesn't change the fact > that they're code at all. They are *both*. That's fine. But what better way to ensure a consistent and stable UI than having it centralized in one place. >> 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. > > I doubt we'll ever reach consensus on this one. I don't think that matters though. qdev properties are part of our UI and need to be stable. Just like we express our command line options centrally (with documentation) via qemu-options.hx, it seems reasonable to me to do it for qdev properties. I think the only downside is that we have to duplicate this the current DeviceInfo definitions but that's a harder problem that can be deferred for another day. >>> 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? > > If no maintainer of QEMU can build with Spice enabled, it got more > serious problems than extracting its documentation. It's not about Spice. But having documentation that is influenced by build options seems like a bad thing to me. But regardless, centralized documentation means more consistency in the documentation. I think this is a critically important point. Regards, Anthony Liguori