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

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 recall this being discussed somewhere recently (probably on the list?). The proper fix IMO is to fix the generator so that it accepts both: enum { /* Some very long description - therefore it's before the value. */ VIR_ENUM_A_VAL = 0, } virEnumA; enum { VIR_ENUM_B_VAL = 0, /* Short description */ } virEnumB;