From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([140.186.70.92]:42052)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1QKYOU-00050b-PF
	for qemu-devel@nongnu.org; Thu, 12 May 2011 12:05:46 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1QKYOQ-0006lt-TU
	for qemu-devel@nongnu.org; Thu, 12 May 2011 12:05:42 -0400
Received: from mail-gw0-f45.google.com ([74.125.83.45]:36585)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1QKYOQ-0006ln-Pd
	for qemu-devel@nongnu.org; Thu, 12 May 2011 12:05:38 -0400
Received: by gwb19 with SMTP id 19so678893gwb.4
	for <qemu-devel@nongnu.org>; Thu, 12 May 2011 09:05:38 -0700 (PDT)
Message-ID: <4DCC054F.7010902@codemonkey.ws>
Date: Thu, 12 May 2011 11:05:35 -0500
From: Anthony Liguori <anthony@codemonkey.ws>
MIME-Version: 1.0
References: <1305023443-8722-1-git-send-email-kraxel@redhat.com>	<201105101624.08253.bradh@frogmouth.net>
	<4DCBA79B.5040608@redhat.com>	<m3d3jo2n1u.fsf@blackfin.pond.sub.org>
	<4DCBFBFF.7000203@redhat.com>
	<m3fwojnc8s.fsf@blackfin.pond.sub.org>
In-Reply-To: <m3fwojnc8s.fsf@blackfin.pond.sub.org>
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: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: Markus Armbruster <armbru@redhat.com>
Cc: amit.shah@redhat.com, Gerd Hoffmann <kraxel@redhat.com>, Brad Hards <bradh@frogmouth.net>, qemu-devel@nongnu.org

On 05/12/2011 10:56 AM, Markus Armbruster wrote:
> Gerd Hoffmann<kraxel@redhat.com>  writes:
>
>>    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?
>
> Anthony ;)

1) It doesn't help us get good written documentation without 
non-existent magic to extract a qdev schema.

2) It makes the documentation hidden in random places in the tree making 
it hard to audit what is undocumented.

3) It guarantees that documentation will vary drastically in language 
and quality.

4) I greatly fear that we're embarking down yet another "introduce a new 
API that never gets fully converted" path.

I've sent a quick patch out with what I think is a significantly better 
approach.

Regards,

Anthony Liguori

>
> [...]
>