From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:59277) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rat7k-0002mG-Uc for qemu-devel@nongnu.org; Wed, 14 Dec 2011 13:00:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rat7e-000489-My for qemu-devel@nongnu.org; Wed, 14 Dec 2011 13:00:12 -0500 Received: from mail-yw0-f45.google.com ([209.85.213.45]:58680) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rat7e-00047h-EQ for qemu-devel@nongnu.org; Wed, 14 Dec 2011 13:00:06 -0500 Received: by yhgg71 with SMTP id g71so1726603yhg.4 for ; Wed, 14 Dec 2011 10:00:05 -0800 (PST) Message-ID: <4EE8E422.40000@codemonkey.ws> Date: Wed, 14 Dec 2011 12:00:02 -0600 From: Anthony Liguori MIME-Version: 1.0 References: <1323879637-16901-1-git-send-email-aliguori@us.ibm.com> <1323879637-16901-2-git-send-email-aliguori@us.ibm.com> <4EE8D506.8090905@codemonkey.ws> <4EE8DABC.8050902@codemonkey.ws> In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Peter Maydell Cc: qemu-devel@nongnu.org, Avi Kivity On 12/14/2011 11:26 AM, Peter Maydell wrote: > On 14 December 2011 17:19, Anthony Liguori wrote: >> If you have a better suggestion, I'm all for it. > > Shrug. I'm not sure what problem you're solving here. To introduce the infrastructure such that we can have high quality internal documentation such that I can use that infrastructure with QEMU Object Model. > The bits > of QEMU that are the worst to understand are the ones which aren't > documented at all, What are the bits that aren't documented at all? An easy answer to that would be "anything that isn't present on http://wiki.qemu.org/docs-internal" How does someone help documented the undocumented things? Send a patch adding gtk-doc style documentation to a file and then once it's merged it will automagically appear on qemu.org. I think that goes a long way to solving the problem. > and the bits where the general structure and > underlying assumptions aren't documented. I'm happy to look in a > header file for specific function API info. I really prefer reading it in the form of a reference document. It also helps enforce a certain amount of consistency in the format of the documentation which is hard to do if there isn't some sort of tool running against it. Regards, Anthony Liguori > -- PMM >