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
