On Mon, May 13, 2013 at 03:04:40PM +0200, Claudio Bley wrote:
At Mon, 13 May 2013 13:39:53 +0100, Daniel P. Berrange wrote:
On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
Hi.
Sometimes, it's a bit hard to determine when exactly a function, flag or macro appeared in libvirt, ie. whether it will be supported on my target machine having a specific version of libvirt or not.
So, I have created an enriched version of the API docs, using a XSL stylesheet enumerating the libvirt?-api.xml files of all libvirt releases.
For an example, you can have a look here:
http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
Hovering over an enum value displays version information in a tooltip.
What do you think? Should this information be included by default in the API docs?
The version an API appeared is not always that useful - since you typically need to know what version a hypervisor driver supported it in.
Yeah, maybe it's a special use case, but when wrapping libvirt functions in Java, I'm interested in the exact version, e.g. to see what's still missing.
FWIW, rather than doing it manually I'd recommend that you create a script which extracts a list of all APIs currently implemented by the java bindings, and then match it against the list of APIs exported in /usr/share/libvirt/api/libvirt-api.xml That's how I validate that the Perl bindings has 100% coverage of all current libvirt APIs: http://libvirt.org/git/?p=libvirt-perl.git;a=blob;f=t/030-api-coverage.t;hb=...
Do you know about this page which shows the version matrix for APIs + drivers:
Yes, but this list is just to overwhelming, I'm almost getting headaches when reading it... ;)
Having to switch back and forth between html/libvirt-libvirt.html and searching in this page is not exactly comfortable by any manner of means.
It's also a lot easier to answer "Which functions where introduced in version x.y.z?" querying the (enriched) libvirt-api.xml than looking it up in this matrix.
But, maybe interlinking these two pages would be sufficient.
On-line filtering by libvirt version and driver support would be even better. What do you think?
I think what would be best is to get the full set of driver support version numbers into the API docs. Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|