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: > > On Thu, May 05, 2022 at 09:48:54AM +0200, Victor Toso wrote: > > > On Wed, May 04, 2022 at 07:02:48PM +0100, Daniel P. Berrangé wrote: > > > > I don't really like the idea of adding stuff to the public API > > > > to workaround brokenness in apibuild.py. > > > > > > While apibuild.py needs to be fixed to error/warn in this > > > scenarios, I'd argue that the patch moves towards consistency > > > with comments blocks and improves the documentation of already > > > exposed API. > > > > > > > It seems like we only need apibuild.py to not merge together > > > > distinct comment blocks. > > > > > > What is not trivial is to (1) define which comment block belongs > > > to which element/type. We need to define what is acceptable and > > > what is not and (2) enforce that to stay consistent. > > > > If we have multiple opened+clsoed comment blocks immediately after > > each other such as this scenario: > > > > /* 1 << 0 is reserved for virDomainModificationImpact */ > > /* 1 << 1 is reserved for virDomainModificationImpact */ > > > > /* Older servers lacked the ability to handle string typed > > * parameters. Attempts to set a string parameter with an older > > * server will fail at the client, but attempts to retrieve > > * parameters must not return strings from a new server to an > > * older client, so this flag exists to identify newer clients to > > * newer servers. This flag is automatically set when needed, so > > * the user does not have to worry about it; however, manually > > * setting the flag can be used to reject servers that cannot > > * return typed strings, even if no strings would be returned. > > * > > * Since: v0.9.8 > > */ > > VIR_TYPED_PARAM_STRING_OKAY = 1 << 2, > > > > 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. With 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 :|
