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