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

On 07/21/2017 01:17 PM, Tomáš Golembiovský wrote: > On Fri, 21 Jul 2017 12:58:55 +0200 > Michal Privoznik <mprivozn(a)redhat.com&gt; wrote: > >> On 07/21/2017 12:25 PM, Tomáš Golembiovský wrote: >>> On Fri, 21 Jul 2017 10:12:38 +0200 >>> Michal Privoznik <mprivozn(a)redhat.com&gt; 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(a)redhat.com&gt; >>>>> --- >>>>> 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