[PATCH v1 0/4] Add 'version' to other exported types

[Andrea Bolognani]

On Tue, Apr 05, 2022 at 08:24:01PM +0200, Victor Toso wrote:
> On Tue, Apr 05, 2022 at 05:01:54PM +0000, Andrea Bolognani wrote:
> > Adding "Since" tags everywhere by hand would be an insane amount of
> > work of course, but we should be able to hack together a script that
> > does something along the lines of
> >
> >   comment = get_comment_for(sym)
> >   version = grab_version_from_allowfile(sym)
> >   replace(comment, f"{comment} (Since {version})")
> >
> > and get like 90% of the way there. We could then make manual
> > adjustments to the stuff that looks off.
>
> Yes, I don't think it is too hard. IMHO, just playing with
> strings at this point. My main concern was the noise it could
> generate over git history. I'm the kind of person that does git
> blame a lot to get the context of a something I'm reading, so
> affecting that is naturally a concern of mine. If it is fine for
> you all, I'm 100% okay with that. It'll take a bit longer but not
> that much. (famous last words)

A lot of the docstrings are multi-line, in which case simply adding a
line will not affect your ability to git blame at all. It's going to
be more disruptive for enum values, but personally I think it's still
a good trade-off: those are usually added once and never touched
afterwards, so you're just adding a single extra step. Note that I
can't guarantee that other developers feel the same way ;)

> > If we wanted to get *really* fancy, we could have some CSS or
> > JavaScript thingy that allows you to select the libvirt version
> > you're targeting and hides or marks in some way the symbols
> > that are newer than that to let you know that you can't use
> > them.
>
> Where would you like to show that?

I literally didn't think that far :) It was just a pie-in-the-sky
idea. Our focus at the moment should be getting accurate "since"
information into the XML API description and HTML API documentation.

-- 
Andrea Bolognani / Red Hat / Virtualization