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

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.