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
