[libvirt] [PATCH] docs: fix documentation of enum constants

[Michal Privoznik]

On 07/21/2017 01:17 PM, Tomáš Golembiovský wrote:
> On Fri, 21 Jul 2017 12:58:55 +0200
> Michal Privoznik <mprivozn at redhat.com> wrote:
> 
>> On 07/21/2017 12:25 PM, Tomáš Golembiovský wrote:
>>> On Fri, 21 Jul 2017 10:12:38 +0200
>>> Michal Privoznik <mprivozn at redhat.com> wrote:
>>>   
>>>> On 07/20/2017 08:21 PM, Tomáš Golembiovský wrote:  
>>>>> The documentation string has to follow the definition of a constant in
>>>>> the enum. Otherwise, the HTML documentation will be generated
>>>>> incorrectly.
>>>>>
>>>>> Signed-off-by: Tomáš Golembiovský <tgolembi at redhat.com>
>>>>> ---
>>>>>  include/libvirt/libvirt-domain.h | 62 ++++++++++++++++++++--------------------
>>>>>  1 file changed, 31 insertions(+), 31 deletions(-)
>>>>>
>>>>> diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
>>>>> index 45f939a8c..2f3162d0f 100644
>>>>> --- a/include/libvirt/libvirt-domain.h
>>>>> +++ b/include/libvirt/libvirt-domain.h
>>>>> @@ -583,56 +583,56 @@ typedef virDomainInterfaceStatsStruct *virDomainInterfaceStatsPtr;
>>>>>   * Memory Statistics Tags:
>>>>>   */
>>>>>  typedef enum {
>>>>> -    /* The total amount of data read from swap space (in kB). */
>>>>>      VIR_DOMAIN_MEMORY_STAT_SWAP_IN         = 0,
>>>>> -    /* The total amount of memory written out to swap space (in kB). */
>>>>> +    /* The total amount of data read from swap space (in kB). */
>>>>>      VIR_DOMAIN_MEMORY_STAT_SWAP_OUT        = 1,
>>>>> +    /* The total amount of memory written out to swap space (in kB). */    
>>>>
>>>> While this fixes generated HTML, it messes up the header file. So if
>>>> somebody is looking directly into header file they might get confused.
>>>> The problem is in our doc generator.  
>>>
>>> I agree that it's not ideal solution. But since it's already used in the
>>> header, e.g. in virDomainBlockJobType and
>>> virDomainEventShutdownDetailType,   
>>
>> This one actually looks okay. Did you perhaps mean
>> virConnectDomainEventDiskChangeReason?
> 
> No, I really meant virDomainEventShutdownDetailType.

Are we looking at the same code? Here's what mine looks like:

typedef enum {
    /* Guest finished shutdown sequence */
    VIR_DOMAIN_EVENT_SHUTDOWN_FINISHED = 0,

    /* Domain finished shutting down after request from the guest itself
     * (e.g. hardware-specific action) */
    VIR_DOMAIN_EVENT_SHUTDOWN_GUEST = 1,

    /* Domain finished shutting down after request from the host (e.g. killed by
     * a signal) */
    VIR_DOMAIN_EVENT_SHUTDOWN_HOST = 2,

# ifdef VIR_ENUM_SENTINELS
    VIR_DOMAIN_EVENT_SHUTDOWN_LAST
# endif
} virDomainEventShutdownDetailType;


I see nothing wrong about it. Do you?

Michal