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

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.

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.

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.

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.

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

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