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

[Anthony Liguori <anthony@codemonkey.ws>]

On 12/14/2011 03:26 PM, Stefan Weil wrote:
> 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.

Look carefully at:

http://qemu.weilnetz.de/gtkdoc/QEMU-Memory-API.html#MemoryRegionOps

vs:

http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html#MemoryRegionOps

There's a significant difference :-)

Regards,

Anthony Liguori

>
> Regards,
> Stefan Weil
>
>