Re: [libvirt] RFC version information in API docs
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.
Do you know about this page which shows the version matrix
for APIs + drivers:
http://libvirt.org/hvsupport.html
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?
Claudio
--
AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany
Phone: +49 341 265 310 19
Web:<http://www.av-test.org>
Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076)
Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern