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

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.