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

Victor Toso victortoso at redhat.com
Tue Apr 5 18:24:01 UTC 2022


Hi,

On Tue, Apr 05, 2022 at 05:01:54PM +0000, Andrea Bolognani wrote:
> On Tue, Apr 05, 2022 at 04:52:10PM +0200, Michal Prívozník wrote:
> > On 4/5/22 13:43, Victor Toso wrote:
> > > As headers are already a great source of documentation for developers,
> > > I'm suggesting to add a specific comment to each of this exported types:
> > >
> > >     /* ... Since <version> */
> > >
> > > For the use case I mentioned above, I'm adding small parsing function in
> > > apibuild.py to fetch the above metadata and included it on the generated
> > > XML API.
> > >
> > > To avoid adding too much noise in the githistory, I'm proposing the
> > > addition of symbols.versions.allowlist file, that apibuild.py can use to
> > > fetch the first git tag that a given symbol appeared in.
> >
> > I like this. It's not only for Golang bindings, but other bindings might
> > benefit from this as well. And also developers reading the docs (they
> > see immediately what version was the symbol they are looking at
> > introduced in).
> >
> > Having said that, maybe we should just add 'Since ...' to every symbol
> > in include/**\.h instead of having it on a side then? If not, then I
> > think scripts/ or docs/ is better location for the allowlist file.

Sorry, missed this part when first read your reply Michal.

> Personally, I think that "since" information should be parsed
> from the docstring.
> 
> Even the thing that we currently do for functions, where we look into
> the .syms file and derive the version number from there, should only
> be used as a way to validate the "since" information contained in the
> corresponding docstring.
> 
> The "allowfile" you've generated could be a first step towards
> reaching the goal, but I don't think it should be something that ends
> up sticking around.
> 
> 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)

> Ideally, the "since" information would also be included in the HTML
> documentation. GLib does that[1] and it's very useful.
>
> To avoid cluttering things too much, we could decide to only
> show "since" information for symbols that have been introduced
> after 1.0.0.

That's 1235 out of 2144. Sounds good to me too.

> 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'm not saying that we should seriously work on that last part,
> it's just the kind of thing that you can unlock once you have
> full version information for every symbol in the API :)

There is always room for improvement, that's for sure. At the
moment, I want to unblock the code generation thing in
libvirt-go-module, somewhat my primary goal. This series is a
part of that quest 0:-)

> [1] https://docs.gtk.org/glib/func.aligned_alloc0.html
> -- 
> Andrea Bolognani / Red Hat / Virtualization

Thanks again for the reviews,
Victor
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20220405/099752ea/attachment.sig>


More information about the libvir-list mailing list