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

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,

I assumed it's acceptable. And the overall readability is not that bad because the constant+doc pairs are separated with newline from one another.

> 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: That would be the best solution, but I'm too scared to look at the generator. That would be a job for somebody else.