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

[Daniel P. Berrange]

On Fri, Jul 21, 2017 at 12:25:02PM +0200, 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, 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'm afraid, those examples are bad too and should never have been committed
as they are, so not a good guide to follow.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|