[libvirt] RFC version information in API docs

[Claudio Bley]

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