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

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.