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

[Tomáš Golembiovský]

On Fri, 21 Jul 2017 13:26:14 +0200
Michal Privoznik <mprivozn at redhat.com> wrote:

> 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:

Damn! We're not. I've been looking at my patched version and
virDomainEventShutdownDetailType was changed by me. Sorry for confusion.

    Tomas

> 
> 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


-- 
Tomáš Golembiovský <tgolembi at redhat.com>