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

[Daniel P. Berrangé]

On Thu, May 05, 2022 at 04:58:10AM -0700, Andrea Bolognani wrote:
> 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.

I'm filled with despair any time I look at a project whose API docs
are generated by Doxygen. All the information is there, but somehow
Doxygen manages to make it awful to find the things you want. To be
fair I think is largely because C is unimaginably flexible.

gtk-doc produces much nicer docs, but it is slightly opinionated
about the way your API is structured and naming conventions in use,
so won't work for all C libraries. It has support for GObject specific
features but you can ignore that. It'd probably be able to make it
work for libvirt with some hacking.

Unfortunately gtk-doc is being pushed towards retirement:

  https://blog.gtk.org/2021/08/19/the-gtk-documentation/

while the code isn't going anywhere, it wont likely get much love
going fowards.

The replacement based on gobject introspection is likely to be quite
challenging to use for libvirt, as it is a bit more opinionated about
API design than even gtk-doc. On the flip side if it were possible to
get gobject introspection working with libvirt, it'd open up ability
to use libvirt from many languages without manually writing bindings.

Finally, even if we did use something else for API docs, we still
actually need apibuild.py to work correctly, because we use it to
expose an XML representation of our API that several language bindings
rely on.

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 :|