From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:51579) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKtMi-0006TB-JG for qemu-devel@nongnu.org; Fri, 13 May 2011 10:29:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QKtMh-00086v-Lb for qemu-devel@nongnu.org; Fri, 13 May 2011 10:29:16 -0400 Received: from mail-yi0-f45.google.com ([209.85.218.45]:35331) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKtMh-00086e-J1 for qemu-devel@nongnu.org; Fri, 13 May 2011 10:29:15 -0400 Received: by yib19 with SMTP id 19so944891yib.4 for ; Fri, 13 May 2011 07:29:14 -0700 (PDT) Message-ID: <4DCD4038.5080009@codemonkey.ws> Date: Fri, 13 May 2011 09:29:12 -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> <4DCC21D2.7000409@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/13/2011 02:35 AM, Markus Armbruster wrote: >> That's fine. But what better way to ensure a consistent and stable UI >> than having it centralized in one place. > > Consistent, stable, and bit-rotten. Unless you come up with a way to > catch bit-rot immediately. That means on "make", not on "make docs". How about make check? See the latest patch. Here is the output from a bad doc file: Warning: device `virtio-9p-pci' is undocumented Warning: device `virtio-balloon-pci' is undocumented Warning: device `virtio-serial-pci' is undocumented Warning: device `virtio-net-pci' is undocumented Warning: device `virtio-blk-pci' is undocumented [ .. snip .. ] Warning: device `x3130-upstream' is undocumented Warning: device `xio3130-downstream' is undocumented Error: device `isa-serial' has documented property `bad-property' with no definition Warning: device `isa-parallel' is undocumented Warning: device `isa-pit' is undocumented [ .. snip .. ] Warning: device `i440FX-xen' is undocumented Warning: device `i440FX' is undocumented Warning: device `i440FX-pcihost' is undocumented Warning: device `vmport' is undocumented Warning: device `ib700' is undocumented Warning: device `isa-debugcon' is undocumented Error: documented device `BadDevice' has no definition 91 warnings, 2 errors. > Extra points if the error message points right to the offending source > line. Would need some macro magic in the qdev registration functions. It's not outside the realm of possibility. >> qdev properties are part of our UI >> and need to be stable. > > Presenting them all to the user in a single document makes sense. > Doesn't follow we have to *write* the documentation in a single place. > > Keeping property documentation in one place makes it soemwhat easier to > keep the properties consistent with each other across devices. > > Property documentation next the device code implementing them makes it > easier to keep the documentation consistent with reality. It also > serves as code documentation. > > It's a trade off. I prefer property documentation next to the code. To > really get consistency across devices, you have to read the resulting > user document, anyway. I see this evolving. To me, this is the start of a qdev schema from which we can generate factory interfaces to each qdev device. >> 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. > > Having to code stuff twice, once in C and once in JSON, is a pretty ugly > downside. At least I didn't submit it using XML ;-) Regards, Anthony Liguori > JSON is a fine data interchange format for programs, but neither a > programming language, nor a document markup language. > > [...] >