On Fri, Jul 21, 2017 at 10:12:38AM +0200, Michal Privoznik 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@xxxxxxxxxx>
> > ---
> > 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.
Yeah, absolutely NACK to this approach. Putting comments after the
constant name is awful for people reading the code.
> 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;
>
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 :|
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
