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

[Andrea Bolognani]

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.

-- 
Andrea Bolognani / Red Hat / Virtualization