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

[Daniel P. Berrangé]

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 :|