Re: [PATCH v1 0/4] Add 'version' to other exported types
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