Re: [Qemu-devel] [PATCH 1/4] memory: make memory API parsable by gtkdoc-scan

[Anthony Liguori <anthony@codemonkey.ws>]

On 12/14/2011 11:26 AM, Peter Maydell wrote:
> On 14 December 2011 17:19, Anthony Liguori<anthony@codemonkey.ws>  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
>