[libvirt PATCH 2/2] include: Explicitly reserve values for overlapping flag types

[Andrea Bolognani]

On Thu, May 05, 2022 at 11:40:55AM +0100, Daniel P. Berrangé wrote:
> On Thu, May 05, 2022 at 02:13:15AM -0700, Andrea Bolognani wrote:
> > On Thu, May 05, 2022 at 08:57:04AM +0100, Daniel P. Berrangé wrote:
> > > IMHO it is pretty straightforward for apibuild.py to have a policy
> > > that the comment block closest to the declaration is the API docs
> > > and the preceeding ones are irrelevant to hte API docs.
> > >
> > > I very much doubt we hav a case where we have multiple open+closed
> > > comment blocks which all should be part of the API docs for a given
> > > declaration, and if we did, then we should merge them into a single
> > > open+closed comment block.
> >
> > This makes sense, at least in theory. I have no idea how difficult it
> > would be to actually convince apibuild.py to behave this way though.
> >
> > I can give it a shot, but I'm concerned about falling into a real
> > rabbit hole with this one. If I don't manage to bend the script to my
> > will quickly enough, I'll just give up on the idea and leave things
> > as they are.
>
> Alternatively the classic approach to this problem taken by javadoc
> and gtk-doc, is to require API comments to use '/**' and leave '/*'
> for non-API comments. We've got a reasonably large amount of usage
> of '/**' but I'm guessing it isn't complete.

Yeah I wouldn't mind if we got rid of same-line comments altogether
and used block comments everywhere. We wouldn't necessarily even have
to change apibuild.py, just update all existing uses. That'd result
in a lot of churn, of course.

Do you have an opinion on the possibility of switching to an
off-the-shelf solution for documenting our API? I name-dropped
Doxygen in the past, but I'm not actually familiar with it. Not sure
how gtk-doc would work for a library that doesn't expose a GLib-based
API.

-- 
Andrea Bolognani / Red Hat / Virtualization