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

[Stefan Weil <sw@weilnetz.de>]

Am 14.12.2011 21:54, schrieb Anthony Liguori:
> On 12/14/2011 02:48 PM, Stefan Weil wrote:
>> Am 14.12.2011 20:03, schrieb Anthony Liguori:
>>> On 12/14/2011 12:54 PM, Stefan Weil wrote:
>>>> Am 14.12.2011 17:34, schrieb malc:
>>>>> On Wed, 14 Dec 2011, Anthony Liguori wrote:
>>>>>
>>>>>> GTK/glib uses a convenient of:
>>>>>>
>>>>>> typedef struct _CamelCase CamelCase;
>>>>>>
>>>>>> The reason that they use a separate struct name is that in C++, 
>>>>>> the struct
>>>>>> namespace not a separate namespace from the type namespace. This 
>>>>>> is actually a
>>>>>> reasonable policy for QEMU to adopt as we eventually start 
>>>>>> exporting C
>>>>>> libraries
>>>>>> that may be consumed by C++ programs.
>>>>>>
>>>>>> I think the use of _ does not violate the C specification as the 
>>>>>> struct
>>>>>> namespace is not the same as the type namespace which is what the 
>>>>>> C spec
>>>>>> refers
>>>>>> to if I understand it correctly.
>>>>>
>>>>> It does violate the standard _ followed by upper case letter is 
>>>>> reserved
>>>>> in all contexts.
>>>>
>>>> sCamelCase instead of _CamelCase seems to work, too.
>>>
>>> Are you sure?
>>>
>>> Take a look at:
>>>
>>> html/QEMU-Memory-API.html#MemoryRegionOps
>>>
>>> It's supposed to look like:
>>>
>>> http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps
>>>
>>> Regards,
>>>
>>> Anthony Liguori
>>
>> I took a look. The html documentation claims that there is a
>> "struct MemoryRegion". There isn't, it's a typedef.
>> Users of the API should use a pointer to a MemoryRegion
>> without knowing details of MemoryRegion, not even whether
>> it is a struct, long or something else.
>
> You should see documentation for each parameter.
>
> At this point, I just patched gtk-doc such that now gtk-doc doesn't 
> require the underscore.
>
> At least the latest version of gtk-doc definitely requires an 
> underscore so having a patched version will be necessary.
>
> Regards,
>
> Anthony Liguori
>


See http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html for
the result which I get with latest QEMU sources, your patch
series v2 and gtk-doc from Debian Squeeze.

Regards,
Stefan Weil